1/*
2 * Off-the-Record Messaging library
3 * Copyright (C) 2004-2012 Ian Goldberg, Chris Alexander, Willy Lew,
4 * Lisa Du, Nikita Borisov
5 * <otr@cypherpunks.ca>
6 *
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of version 2.1 of the GNU Lesser General
9 * Public License as published by the Free Software Foundation.
10 *
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with this library; if not, write to the Free Software
18 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
19 */
20
21#ifndef __PRIVKEY_H__
22#define __PRIVKEY_H__
23
24#include <stdio.h>
25#include "privkey-t.h"
26#include "userstate.h"
27
28/* The length of a string representing a human-readable version of a
29 * fingerprint (including the trailing NUL) */
30#define OTRL_PRIVKEY_FPRINT_HUMAN_LEN 45
31
32/* Convert a 20-byte hash value to a 45-byte human-readable value */
33void otrl_privkey_hash_to_human(
34 char human[OTRL_PRIVKEY_FPRINT_HUMAN_LEN],
35 const unsigned char hash[20]);
36
37/* Calculate a human-readable hash of our DSA public key. Return it in
38 * the passed fingerprint buffer. Return NULL on error, or a pointer to
39 * the given buffer on success. */
40char *otrl_privkey_fingerprint(OtrlUserState us,
41 char fingerprint[OTRL_PRIVKEY_FPRINT_HUMAN_LEN],
42 const char *accountname, const char *protocol);
43
44/* Calculate a raw hash of our DSA public key. Return it in the passed
45 * fingerprint buffer. Return NULL on error, or a pointer to the given
46 * buffer on success. */
47unsigned char *otrl_privkey_fingerprint_raw(OtrlUserState us,
48 unsigned char hash[20], const char *accountname, const char *protocol);
49
50/* Read a sets of private DSA keys from a file on disk into the given
51 * OtrlUserState. */
52gcry_error_t otrl_privkey_read(OtrlUserState us, const char *filename);
53
54/* Read a sets of private DSA keys from a FILE* into the given
55 * OtrlUserState. The FILE* must be open for reading. */
56gcry_error_t otrl_privkey_read_FILEp(OtrlUserState us, FILE *privf);
57
58/* Free the memory associated with the pending privkey list */
59void otrl_privkey_pending_forget_all(OtrlUserState us);
60
61/* Begin a private key generation that will potentially take place in
62 * a background thread. This routine must be called from the main
63 * thread. It will set *newkeyp, which you can pass to
64 * otrl_privkey_generate_calculate in a background thread. If it
65 * returns gcry_error(GPG_ERR_EEXIST), then a privkey creation for
66 * this accountname/protocol is already in progress, and *newkeyp will
67 * be set to NULL. */
68gcry_error_t otrl_privkey_generate_start(OtrlUserState us,
69 const char *accountname, const char *protocol, void **newkeyp);
70
71/* Do the private key generation calculation. You may call this from a
72 * background thread. When it completes, call
73 * otrl_privkey_generate_finish from the _main_ thread. */
74gcry_error_t otrl_privkey_generate_calculate(void *newkey);
75
76/* Call this from the main thread only. It will write the newly created
77 * private key into the given file and store it in the OtrlUserState. */
78gcry_error_t otrl_privkey_generate_finish(OtrlUserState us,
79 void *newkey, const char *filename);
80
81/* Call this from the main thread only. It will write the newly created
82 * private key into the given FILE* (which must be open for reading and
83 * writing) and store it in the OtrlUserState. */
84gcry_error_t otrl_privkey_generate_finish_FILEp(OtrlUserState us,
85 void *newkey, FILE *privf);
86
87/* Call this from the main thread only, in the event that the background
88 * thread generating the key is cancelled. The newkey is deallocated,
89 * and must not be used further. */
90void otrl_privkey_generate_cancelled(OtrlUserState us, void *newkey);
91
92/* Generate a private DSA key for a given account, storing it into a
93 * file on disk, and loading it into the given OtrlUserState. Overwrite any
94 * previously generated keys for that account in that OtrlUserState. */
95gcry_error_t otrl_privkey_generate(OtrlUserState us, const char *filename,
96 const char *accountname, const char *protocol);
97
98/* Generate a private DSA key for a given account, storing it into a
99 * FILE*, and loading it into the given OtrlUserState. Overwrite any
100 * previously generated keys for that account in that OtrlUserState.
101 * The FILE* must be open for reading and writing. */
102gcry_error_t otrl_privkey_generate_FILEp(OtrlUserState us, FILE *privf,
103 const char *accountname, const char *protocol);
104
105/* Read the fingerprint store from a file on disk into the given
106 * OtrlUserState. Use add_app_data to add application data to each
107 * ConnContext so created. */
108gcry_error_t otrl_privkey_read_fingerprints(OtrlUserState us,
109 const char *filename,
110 void (*add_app_data)(void *data, ConnContext *context),
111 void *data);
112
113/* Read the fingerprint store from a FILE* into the given
114 * OtrlUserState. Use add_app_data to add application data to each
115 * ConnContext so created. The FILE* must be open for reading. */
116gcry_error_t otrl_privkey_read_fingerprints_FILEp(OtrlUserState us,
117 FILE *storef,
118 void (*add_app_data)(void *data, ConnContext *context),
119 void *data);
120
121/* Write the fingerprint store from a given OtrlUserState to a file on disk. */
122gcry_error_t otrl_privkey_write_fingerprints(OtrlUserState us,
123 const char *filename);
124
125/* Write the fingerprint store from a given OtrlUserState to a FILE*.
126 * The FILE* must be open for writing. */
127gcry_error_t otrl_privkey_write_fingerprints_FILEp(OtrlUserState us,
128 FILE *storef);
129
130/* Fetch the private key from the given OtrlUserState associated with
131 * the given account */
132OtrlPrivKey *otrl_privkey_find(OtrlUserState us, const char *accountname,
133 const char *protocol);
134
135/* Forget a private key */
136void otrl_privkey_forget(OtrlPrivKey *privkey);
137
138/* Forget all private keys in a given OtrlUserState. */
139void otrl_privkey_forget_all(OtrlUserState us);
140
141/* Sign data using a private key. The data must be small enough to be
142 * signed (i.e. already hashed, if necessary). The signature will be
143 * returned in *sigp, which the caller must free(). Its length will be
144 * returned in *siglenp. */
145gcry_error_t otrl_privkey_sign(unsigned char **sigp, size_t *siglenp,
146 OtrlPrivKey *privkey, const unsigned char *data, size_t len);
147
148/* Verify a signature on data using a public key. The data must be
149 * small enough to be signed (i.e. already hashed, if necessary). */
150gcry_error_t otrl_privkey_verify(const unsigned char *sigbuf, size_t siglen,
151 unsigned short pubkey_type, gcry_sexp_t pubs,
152 const unsigned char *data, size_t len);
153
154#endif
155