See ChangeLog: Sat Sep 18 12:16:08 CEST 1999 Werner Koch
[libgcrypt.git] / src / gcrypt.h
1 /* gcrypt.h -  GNU digital encryption library interface
2  *      Copyright (C) 1998 Free Software Foundation, Inc.
3  *
4  * This file is part of GnuPG.
5  *
6  * GnuPG is free software; you can redistribute it and/or modify
7  * it under the terms of the GNU General Public License as published by
8  * the Free Software Foundation; either version 2 of the License, or
9  * (at your option) any later version.
10  *
11  * GnuPG 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
14  * GNU General Public License for more details.
15  *
16  * You should have received a copy of the GNU General Public License
17  * along with this program; if not, write to the Free Software
18  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
19  */
20
21 #ifndef _GCRYPT_H
22 #define _GCRYPT_H
23 #ifdef __cplusplus
24 extern "C" {
25 #endif
26
27
28 #ifndef HAVE_BYTE_TYPEDEF
29   #undef byte       /* maybe there is a macro with this name */
30   typedef unsigned char byte;
31   #define HAVE_BYTE_TYPEDEF
32 #endif
33
34 /*******************************************
35  *                                         *
36  *  error handling etc.                    *
37  *                                         *
38  *******************************************/
39
40 enum {
41     GCRYERR_SUCCESS = 0,    /* "no error" */
42     GCRYERR_GENERAL = 1,    /* catch all the other errors code */
43     GCRYERR_INV_OP = 2,     /* invalid operation code or ctl command */
44     GCRYERR_NOMEM = 3,      /* out of core */
45     GCRYERR_INV_ALGO = 4,   /* invalid algorithm */
46     GCRYERR_INV_ARG = 5,    /* invalid argument */
47     GCRYERR_INTERNAL = 6,   /* internal error */
48     GCRYERR_EOF = 7,        /* (-1) is remapped to this value */
49     GCRYERR_TOO_SHORT = 8,  /* provided buffer too short */
50     GCRYERR_TOO_LARGE = 9,  /* object is too large */
51     GCRYERR_INV_OBJ = 10,   /* an object is not valid */
52 };
53
54
55 int gcry_errno(void);
56 const char *gcry_strerror( int ec );
57
58 enum gcry_ctl_cmds {
59     GCRYCTL_SET_KEY  = 1,
60     GCRYCTL_SET_IV   = 2,
61     GCRYCTL_CFB_SYNC = 3,
62     GCRYCTL_RESET    = 4,   /* e.g. for MDs */
63     GCRYCTL_FINALIZE = 5,
64     GCRYCTL_GET_KEYLEN = 6,
65     GCRYCTL_GET_BLKLEN = 7,
66     GCRYCTL_TEST_ALGO = 8,
67 };
68
69 int gcry_control( enum gcry_ctl_cmds, ... );
70
71 enum gcry_random_level {
72     GCRY_WEAK_RANDOM = 0,
73     GCRY_STRONG_RANDOM = 1,
74     GCRY_VERY_STRONG_RANDOM = 2
75 };
76
77
78 struct gcry_sexp;
79 typedef struct gcry_sexp *GCRY_SEXP;
80
81 enum gcry_sexp_format {
82     GCRYSEXP_FMT_DEFAULT   = 0,
83     GCRYSEXP_FMT_CANON     = 1,
84     GCRYSEXP_FMT_BASE64    = 2,
85     GCRYSEXP_FMT_ADVANCED  = 3,
86 };
87
88
89 GCRY_SEXP gcry_sexp_new( const char *buffer, size_t length );
90 void gcry_sexp_release( GCRY_SEXP sexp );
91 GCRY_SEXP gcry_sexp_cons( GCRY_SEXP a, GCRY_SEXP b );
92 GCRY_SEXP gcry_sexp_vlist( GCRY_SEXP a, ... );
93 int  gcry_sexp_sscan( GCRY_SEXP *retsexp, const char *buffer,
94                                size_t length, size_t *erroff );
95 size_t gcry_sexp_sprint( GCRY_SEXP sexp, int mode, char *buffer,
96                                                 size_t maxlength );
97
98 #ifndef GCRYPT_NO_SEXP_MACROS
99 #define SEXP            GCRY_SEXP
100 #define SEXP_NEW(a,b)   gcry_sexp_new_data( (a), (b) )
101 #define SEXP_RELEASE(a) do { gcry_sexp_release( (a) ); (a)=NULL; } while(0)
102 #define SEXP_CONS(a,b)  gcry_sexp_cons((a),(b))
103 #endif /*GCRYPT_NO_SEXP_MACROS*/
104
105 /*******************************************
106  *                                         *
107  *  multi precision integer functions      *
108  *                                         *
109  *******************************************/
110
111 enum gcry_mpi_format {
112     GCRYMPI_FMT_STD = 0,    /* twos complement stored without length */
113     GCRYMPI_FMT_PGP = 1,    /* As used by OpenPGP */
114     GCRYMPI_FMT_SSH = 2,    /* As used by SSH (same as 0 but with length)*/
115     GCRYMPI_FMT_HEX = 3,    /* hex format */
116     GCRYMPI_FMT_USG = 4,    /* like STD but this is an unsigned one */
117 };
118
119 struct gcry_mpi;
120 typedef struct gcry_mpi *GCRY_MPI;
121
122 GCRY_MPI gcry_mpi_new( unsigned int nbits );
123 GCRY_MPI gcry_mpi_snew( unsigned int nbits );
124 void     gcry_mpi_release( GCRY_MPI a );
125 GCRY_MPI gcry_mpi_copy( const GCRY_MPI a );
126 GCRY_MPI gcry_mpi_set( GCRY_MPI w, const GCRY_MPI u );
127 GCRY_MPI gcry_mpi_set_ui( GCRY_MPI w, unsigned long u );
128 int      gcry_mpi_cmp( const GCRY_MPI u, const GCRY_MPI v );
129 int      gcry_mpi_cmp_ui( const GCRY_MPI u, unsigned long v );
130 void     gcry_mpi_randomize( GCRY_MPI w,
131                              unsigned int nbits, enum gcry_random_level level);
132 int      gcry_mpi_scan( GCRY_MPI *ret_mpi, enum gcry_mpi_format format,
133                                        const char *buffer, size_t *nbytes );
134 int      gcry_mpi_print( enum gcry_mpi_format format,
135                          char *buffer, size_t *nbytes, const GCRY_MPI a );
136
137 void gcry_mpi_powm( GCRY_MPI w,
138                     const GCRY_MPI b, const GCRY_MPI e, const GCRY_MPI m );
139
140
141 #ifndef GCRYPT_NO_MPI_MACROS
142 #define mpi_new(n)          gcry_mpi_new( (n) )
143 #define mpi_secure_new( n ) gcry_mpi_snew( (n) )
144 #define mpi_release( a )    do { gcry_mpi_release( (a) ); \
145                                  (a) = NULL; } while(0)
146 #define mpi_copy( a )       gcry_mpi_copy( (a) )
147 #define mpi_set( w, u)      gcry_mpi_set( (w), (u) )
148 #define mpi_set_ui( w, u)   gcry_mpi_set_ui( (w), (u) )
149 #define mpi_cmp( u, v )     gcry_mpi_cmp( (u), (v) )
150 #define mpi_cmp_ui( u, v )  gcry_mpi_cmp_ui( (u), (v) )
151
152 #define mpi_powm(w,b,e,m)   gcry_mpi_powm( (w), (b), (e), (m) )
153 #endif /* GCRYPT_NO_MPI_MACROS */
154
155 /********************************************
156  *******  symmetric cipher functions  *******
157  ********************************************/
158
159 struct gcry_cipher_context;
160 typedef struct gcry_cipher_context *GCRY_CIPHER_HD;
161
162 enum gcry_cipher_algos {
163     GCRY_CIPHER_NONE        = 0,
164     GCRY_CIPHER_IDEA        = 1,
165     GCRY_CIPHER_3DES        = 2,
166     GCRY_CIPHER_CAST5       = 3,
167     GCRY_CIPHER_BLOWFISH    = 4,
168     GCRY_CIPHER_SAFER_SK128 = 5,
169     GCRY_CIPHER_DES_SK      = 6
170 };
171
172 enum gcry_cipher_modes {
173     GCRY_CIPHER_MODE_NONE   = 0,
174     GCRY_CIPHER_MODE_ECB    = 1,
175     GCRY_CIPHER_MODE_CFB    = 2,
176     GCRY_CIPHER_MODE_CBC    = 3,
177 };
178
179 enum gcry_cipher_flags {
180     GCRY_CIPHER_SECURE      = 1,  /* allocate in secure memory */
181     GCRY_CIPHER_ENABLE_SYNC = 2,  /* enable CFB sync mode */
182 };
183
184
185 #if 0 /* not yet done */
186 int gcry_string_to_cipher_algo( const char *string );
187 int gcry_check_cipher_algo( int algo );
188 #endif
189
190 GCRY_CIPHER_HD r gcry_cipher_open( int algo, int mode, unsigned flags);
191 void gcry_cipher_close( GCRY_CIPHER_HD h );
192 int  gcry_cipher_ctl( GCRY_CIPHER_HD h, int cmd, byte *buffer, size_t buflen);
193 int gcry_cipher_info( GCRY_CIPHER_HD h, int what, void *buffer, size_t *nbytes);
194 int gcry_cipher_algo_info( int algo, int what, void *buffer, size_t *nbytes);
195 const char *gcry_cipher_algo_name( int algo );
196
197 int gcry_cipher_encrypt( GCRY_CIPHER_HD h, byte *out, size_t outsize,
198                                       const byte *in, size_t inlen );
199 int gcry_cipher_decrypt( GCRY_CIPHER_HD h, byte *out, size_t outsize,
200                                       const byte *in, size_t inlen );
201
202
203 /* some handy macros */
204 #define gcry_cipher_setkey(h,k,l)  gcry_cipher_ctl( (h), GCRYCTL_SET_KEY, \
205                                                                   (k), (l) )
206 #define gcry_cipher_setiv(h,k,l)  gcry_cipher_ctl( (h), GCRYCTL_SET_IV, \
207                                                                   (k), (l) )
208 #define gcry_cipher_sync(h)  gcry_cipher_ctl( (h), GCRYCTL_CFB_SYNC, \
209                                                                    NULL, 0 )
210
211 #define gcry_cipher_get_algo_keylen(a) \
212             gcry_cipher_algo_info( (a), GCRYCTL_GET_KEYLEN, NULL, NULL );
213 #define gcry_cipher_get_algo_blklen(a) \
214             gcry_cipher_algo_info( (a), GCRYCTL_GET_BLKLEN, NULL, NULL );
215 #define gcry_cipher_test_algo(a) \
216             gcry_cipher_algo_info( (a), GCRYCTL_TEST_ALGO, NULL, NULL );
217
218
219 /*********************************************
220  *******  asymmetric cipher functions  *******
221  *********************************************/
222
223 int gcry_pk_encrypt( GCRY_SEXP *result, GCRY_SEXP data, GCRY_SEXP pkey );
224 int gcry_pk_decrypt( GCRY_SEXP *result, GCRY_SEXP data, GCRY_SEXP skey );
225 int gcry_pk_sign(    GCRY_SEXP *result, GCRY_SEXP data, GCRY_SEXP skey );
226 int gcry_pk_verify(  GCRY_SEXP *result, GCRY_SEXP data, GCRY_SEXP pkey );
227
228
229 /*********************************************
230  *******  cryptograhic hash functions  *******
231  *********************************************/
232
233 struct gcry_md_context;
234 typedef struct gcry_md_context *GCRY_MD_HD; /* same as the old MD_HANDLE */
235
236 enum gcry_md_algos {
237     GCRY_MD_NONE    = 0,
238     GCRY_MD_MD5     = 1,
239     GCRY_MD_SHA1    = 2,
240     GCRY_MD_RMD160  = 3,
241     GCRY_MD_TIGER   = 6
242 };
243
244 enum gcry_md_flags {
245     GCRY_MD_FLAG_SECURE = 1
246 };
247
248
249 GCRY_MD_HD gcry_md_open( int algo, unsigned flags );
250 void gcry_md_close( GCRY_MD_HD hd );
251 int gcry_md_enable( GCRY_MD_HD hd, int algo );
252 GCRY_MD_HD gcry_md_copy( GCRY_MD_HD hd );
253 int gcry_md_ctl( GCRY_MD_HD hd, int cmd, byte *buffer, size_t buflen);
254 void gcry_md_write( GCRY_MD_HD hd, const byte *buffer, size_t length);
255 byte *gcry_md_read( GCRY_MD_HD hd, int algo );
256 int gcry_md_get_algo( GCRY_MD_HD hd );
257 int gcry_md_get_dlen( int algo );
258 /*??int gcry_md_get( GCRY_MD_HD hd, int algo, byte *buffer, int buflen );*/
259
260
261 /*****************************************
262  *******  miscellaneous functions  *******
263  *****************************************/
264
265 #if 0
266 const char *g10m_revision_string(int mode);
267 const char *g10c_revision_string(int mode);
268 const char *g10u_revision_string(int mode);
269
270 MPI   g10c_generate_secret_prime( unsigned nbits );
271 char *g10c_get_random_bits( unsigned nbits, int level, int secure );
272
273
274 void *g10_malloc( size_t n );
275 void *g10_calloc( size_t n );
276 void *g10_malloc_secure( size_t n );
277 void *g10_calloc_secure( size_t n );
278 void *g10_realloc( void *a, size_t n );
279 void  g10_free( void *p );
280 char *g10_strdup( const char * a);
281
282 void g10_log_bug( const char *fmt, ... );
283 void g10_log_bug0( const char *, int );
284 void g10_log_fatal( const char *fmt, ... );
285 void g10_log_error( const char *fmt, ... );
286 void g10_log_info( const char *fmt, ... );
287 void g10_log_debug( const char *fmt, ... );
288 void g10_log_hexdump( const char *text, char *buf, size_t len );
289 void g10_log_mpidump( const char *text, MPI a );
290 #endif
291
292 /***************************
293  *******  constants  *******
294  **************************/
295 #if 0
296 #define CIPHER_ALGO_NONE         0
297 #define CIPHER_ALGO_IDEA         1
298 #define CIPHER_ALGO_3DES         2
299 #define CIPHER_ALGO_CAST5        3
300 #define CIPHER_ALGO_BLOWFISH     4  /* blowfish 128 bit key */
301 #define CIPHER_ALGO_SAFER_SK128  5
302 #define CIPHER_ALGO_DES_SK       6
303 #define CIPHER_ALGO_DUMMY      110  /* no encryption at all */
304
305 #define PUBKEY_ALGO_RSA        1
306 #define PUBKEY_ALGO_RSA_E      2     /* RSA encrypt only */
307 #define PUBKEY_ALGO_RSA_S      3     /* RSA sign only */
308 #define PUBKEY_ALGO_ELGAMAL_E 16     /* encrypt only ElGamal (but not for v3)*/
309 #define PUBKEY_ALGO_DSA       17
310 #define PUBKEY_ALGO_ELGAMAL   20     /* sign and encrypt elgamal */
311
312 #define DIGEST_ALGO_MD5       1
313 #define DIGEST_ALGO_SHA1      2
314 #define DIGEST_ALGO_RMD160    3
315 #define DIGEST_ALGO_TIGER     6
316
317 #define is_RSA(a)     ((a)==PUBKEY_ALGO_RSA || (a)==PUBKEY_ALGO_RSA_E \
318                        || (a)==PUBKEY_ALGO_RSA_S )
319 #define is_ELGAMAL(a) ((a)==PUBKEY_ALGO_ELGAMAL || (a)==PUBKEY_ALGO_ELGAMAL_E)
320
321 #define G10ERR_GENERAL         1
322 #define G10ERR_PUBKEY_ALGO     4
323 #define G10ERR_DIGEST_ALGO     5
324 #define G10ERR_BAD_PUBKEY      6
325 #define G10ERR_BAD_SECKEY      7
326 #define G10ERR_BAD_SIGN        8
327 #define G10ERR_CIPHER_ALGO    12
328 #define G10ERR_WRONG_SECKEY   18
329 #define G10ERR_UNSUPPORTED    19
330 #define G10ERR_NI_PUBKEY      27
331 #define G10ERR_NI_CIPHER      28
332 #define G10ERR_BAD_MPI        30
333 #define G10ERR_WR_PUBKEY_ALGO 41
334 #endif
335
336 /***********************************************
337  *                                             *
338  *   Some very handy macros                    *
339  *                                             *
340  ***********************************************/
341 #ifndef GCRYPT_NO_MPI_MACROS
342
343 typedef struct gcry_mpi *MPI;
344
345
346 #endif /* GCRYPT_NO_MPI_MACROS */
347
348 #ifdef __cplusplus
349 }
350 #endif
351 #endif /* _GCRYPT_H */