See ChangeLog: Thu Dec 9 17:22:27 CET 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
24 #include <stdarg.h>
25
26 #ifdef __cplusplus
27 extern "C" {
28 #endif
29
30 /*
31  * The version of this header should match the one of the library
32  * It should not be used by a program because gcry_check_version()
33  * should reurn the same version.  The purpose of this macro is to
34  * let autoconf (using the AM_PATH_GCRYPT macro) check that this
35  * header matches the installed library.
36  * Note: Do not edit the next line as configure may fix the string here.
37  */
38 #define GCRYPT_VERSION "1.1.0a"
39
40
41 #ifndef HAVE_BYTE_TYPEDEF
42 # undef byte       /* maybe there is a macro with this name */
43   typedef unsigned char byte;
44 # define HAVE_BYTE_TYPEDEF
45 #endif
46
47 #ifdef _GCRYPT_IN_LIBGCRYPT
48 # ifndef GCRYPT_NO_MPI_MACROS
49 #   define GCRYPT_NO_MPI_MACROS 1
50 # endif
51 #endif
52
53 struct gcry_mpi;
54 typedef struct gcry_mpi *GCRY_MPI;
55
56 /*******************************************
57  *                                         *
58  *  error handling etc.                    *
59  *                                         *
60  *******************************************/
61
62 /* FIXME: We should use the same values as they were used in GnuPG 1.0.
63  *        gpg --status-fd may print some of these values */
64 enum {
65     GCRYERR_SUCCESS = 0,    /* "no error" */
66     GCRYERR_GENERAL = 1,    /* catch all the other errors code */
67
68     GCRYERR_INV_PK_ALGO = 4, /* invalid public key algorithm */
69     GCRYERR_INV_MD_ALGO = 5, /* invalid message digest algorithm */
70     GCRYERR_BAD_PUBLIC_KEY = 6, /* Bad public key */
71     GCRYERR_BAD_SECRET_KEY = 7, /* Bad secret key */
72     GCRYERR_BAD_SIGNATURE = 8,  /* Bad signature */
73
74     GCRYERR_INV_CIPHER_ALGO = 12, /* invalid cipher algorithm */
75     GCRYERR_BAD_MPI = 30,
76     GCRYERR_WRONG_PK_ALGO = 41, /* wrong public key algorithm */
77     GCRYERR_WEAK_KEY = 43,  /* weak encryption key */
78     GCRYERR_INV_KEYLEN = 44,  /* invalid length of a key*/
79     GCRYERR_INV_ARG = 45,    /* invalid argument */
80     GCRYERR_SELFTEST = 50,      /* selftest failed */
81
82     /* error codes not used in GnuPG 1.0 */
83     GCRYERR_INV_OP = 61,     /* invalid operation code or ctl command */
84     GCRYERR_NO_MEM = 62,     /* out of core */
85     GCRYERR_INTERNAL = 63,   /* internal error */
86     GCRYERR_EOF = 64,        /* (-1) is remapped to this value */
87     GCRYERR_INV_OBJ = 65,    /* an object is not valid */
88     GCRYERR_TOO_SHORT = 66,  /* provided buffer too short */
89     GCRYERR_TOO_LARGE = 67,  /* object is too large */
90     GCRYERR_NO_OBJ = 68,     /* Missign item in an object */
91 };
92
93 const char *gcry_check_version( const char *req_version );
94
95 int gcry_errno(void);
96 const char *gcry_strerror( int ec );
97
98 enum gcry_ctl_cmds {
99     GCRYCTL_SET_KEY  = 1,
100     GCRYCTL_SET_IV   = 2,
101     GCRYCTL_CFB_SYNC = 3,
102     GCRYCTL_RESET    = 4,   /* e.g. for MDs */
103     GCRYCTL_FINALIZE = 5,
104     GCRYCTL_GET_KEYLEN = 6,
105     GCRYCTL_GET_BLKLEN = 7,
106     GCRYCTL_TEST_ALGO = 8,
107     GCRYCTL_IS_SECURE = 9,
108     GCRYCTL_GET_ASNOID = 10,
109     GCRYCTL_ENABLE_ALGO = 11,
110     GCRYCTL_DISABLE_ALGO = 12,
111     GCRYCTL_DUMP_RANDOM_STATS = 13,
112     GCRYCTL_DUMP_SECMEM_STATS = 14,
113     GCRYCTL_GET_ALGO_NPKEY    = 15,
114     GCRYCTL_GET_ALGO_NSKEY    = 16,
115     GCRYCTL_GET_ALGO_NSIGN    = 17,
116     GCRYCTL_GET_ALGO_NENCR    = 18,
117     GCRYCTL_SET_VERBOSITY     = 19,
118     GCRYCTL_SET_DEBUG_FLAGS   = 20,
119     GCRYCTL_CLEAR_DEBUG_FLAGS = 21,
120     GCRYCTL_USE_SECURE_RNDPOOL= 22,
121 };
122
123 int gcry_control( enum gcry_ctl_cmds, ... );
124
125 enum gcry_random_level {
126     GCRY_WEAK_RANDOM = 0,
127     GCRY_STRONG_RANDOM = 1,
128     GCRY_VERY_STRONG_RANDOM = 2
129 };
130
131
132 struct gcry_sexp;
133 typedef struct gcry_sexp *GCRY_SEXP;
134
135 enum gcry_sexp_format {
136     GCRYSEXP_FMT_DEFAULT   = 0,
137     GCRYSEXP_FMT_CANON     = 1,
138     GCRYSEXP_FMT_BASE64    = 2,
139     GCRYSEXP_FMT_ADVANCED  = 3,
140 };
141
142
143 GCRY_SEXP gcry_sexp_new_data( const char *buffer, size_t length );
144 GCRY_SEXP gcry_sexp_new_mpi( GCRY_MPI mpi );
145 GCRY_SEXP gcry_sexp_new_name_data( const char *name,
146                                    const char *buffer, size_t length );
147 GCRY_SEXP gcry_sexp_new_name_mpi( const char *name, GCRY_MPI mpi );
148 void      gcry_sexp_release( GCRY_SEXP sexp );
149 void      gcry_sexp_dump( GCRY_SEXP a );
150 GCRY_SEXP gcry_sexp_cons( GCRY_SEXP a, GCRY_SEXP b );
151 GCRY_SEXP gcry_sexp_vlist( GCRY_SEXP a, ... );
152 GCRY_SEXP gcry_sexp_append( GCRY_SEXP a, GCRY_SEXP n );
153 GCRY_SEXP gcry_sexp_prepend( GCRY_SEXP a, GCRY_SEXP n );
154 int       gcry_sexp_sscan( GCRY_SEXP *retsexp, const char *buffer,
155                                size_t length, size_t *erroff );
156 size_t      gcry_sexp_sprint( GCRY_SEXP sexp, int mode, char *buffer,
157                                                 size_t maxlength );
158 GCRY_SEXP   gcry_sexp_find_token( GCRY_SEXP list,
159                                   const char *tok, size_t toklen );
160 GCRY_SEXP   gcry_sexp_car( GCRY_SEXP list );
161 GCRY_SEXP   gcry_sexp_cdr( GCRY_SEXP list );
162 const char *gcry_sexp_car_data( GCRY_SEXP list, size_t *datalen );
163 const char *gcry_sexp_cdr_data( GCRY_SEXP list, size_t *datalen );
164 GCRY_MPI    gcry_sexp_car_mpi( GCRY_SEXP list, int mpifmt );
165 GCRY_MPI    gcry_sexp_cdr_mpi( GCRY_SEXP list, int mpifmt );
166
167
168
169 #ifndef GCRYPT_NO_SEXP_MACROS
170 #define SEXP            GCRY_SEXP
171 #define SEXP_NEW(a,b)   gcry_sexp_new_data( (a), (b) )
172 #define SEXP_RELEASE(a) do { gcry_sexp_release( (a) ); (a)=NULL; } while(0)
173 #define SEXP_CONS(a,b)  gcry_sexp_cons((a),(b))
174 #endif /*GCRYPT_NO_SEXP_MACROS*/
175
176 /*******************************************
177  *                                         *
178  *  multi precision integer functions      *
179  *                                         *
180  *******************************************/
181
182 enum gcry_mpi_format {
183     GCRYMPI_FMT_NONE= 0,
184     GCRYMPI_FMT_STD = 1,    /* twos complement stored without length */
185     GCRYMPI_FMT_PGP = 2,    /* As used by OpenPGP */
186     GCRYMPI_FMT_SSH = 3,    /* As used by SSH (same as 0 but with length)*/
187     GCRYMPI_FMT_HEX = 4,    /* hex format */
188     GCRYMPI_FMT_USG = 5,    /* like STD but this is an unsigned one */
189 };
190
191
192 enum gcry_mpi_flag {
193     GCRYMPI_FLAG_SECURE = 1,
194     GCRYMPI_FLAG_OPAQUE = 2,
195 };
196
197
198
199 GCRY_MPI gcry_mpi_new( unsigned int nbits );
200 GCRY_MPI gcry_mpi_snew( unsigned int nbits );
201 void     gcry_mpi_release( GCRY_MPI a );
202 GCRY_MPI gcry_mpi_copy( const GCRY_MPI a );
203 GCRY_MPI gcry_mpi_set( GCRY_MPI w, const GCRY_MPI u );
204 GCRY_MPI gcry_mpi_set_ui( GCRY_MPI w, unsigned long u );
205 int      gcry_mpi_cmp( const GCRY_MPI u, const GCRY_MPI v );
206 int      gcry_mpi_cmp_ui( const GCRY_MPI u, unsigned long v );
207 void     gcry_mpi_randomize( GCRY_MPI w,
208                              unsigned int nbits, enum gcry_random_level level);
209 int      gcry_mpi_scan( GCRY_MPI *ret_mpi, enum gcry_mpi_format format,
210                                        const char *buffer, size_t *nbytes );
211 int      gcry_mpi_print( enum gcry_mpi_format format,
212                          char *buffer, size_t *nbytes, const GCRY_MPI a );
213
214 void gcry_mpi_powm( GCRY_MPI w,
215                     const GCRY_MPI b, const GCRY_MPI e, const GCRY_MPI m );
216 GCRY_MPI gcry_mpi_set_opaque( GCRY_MPI a, void *p, unsigned int nbits );
217 void    *gcry_mpi_get_opaque( GCRY_MPI a, unsigned int *nbits );
218 void gcry_mpi_set_flag( GCRY_MPI a, enum gcry_mpi_flag flag );
219 void gcry_mpi_clear_flag( GCRY_MPI a, enum gcry_mpi_flag flag );
220 int  gcry_mpi_get_flag( GCRY_MPI a, enum gcry_mpi_flag flag );
221
222
223 #ifndef GCRYPT_NO_MPI_MACROS
224 #define mpi_new(n)          gcry_mpi_new( (n) )
225 #define mpi_secure_new( n ) gcry_mpi_snew( (n) )
226 #define mpi_release( a )    do { gcry_mpi_release( (a) ); \
227                                  (a) = NULL; } while(0)
228 #define mpi_copy( a )       gcry_mpi_copy( (a) )
229 #define mpi_set( w, u)      gcry_mpi_set( (w), (u) )
230 #define mpi_set_ui( w, u)   gcry_mpi_set_ui( (w), (u) )
231 #define mpi_cmp( u, v )     gcry_mpi_cmp( (u), (v) )
232 #define mpi_cmp_ui( u, v )  gcry_mpi_cmp_ui( (u), (v) )
233
234 #define mpi_powm(w,b,e,m)   gcry_mpi_powm( (w), (b), (e), (m) )
235 #define mpi_set_opaque(a,b,c) gcry_mpi_set_opaque( (a), (b), (c) )
236 #define mpi_get_opaque(a,b)   gcry_mpi_get_opaque( (a), (b) )
237 #endif /* GCRYPT_NO_MPI_MACROS */
238
239 /********************************************
240  *******  symmetric cipher functions  *******
241  ********************************************/
242
243 struct gcry_cipher_handle;
244 typedef struct gcry_cipher_handle *GCRY_CIPHER_HD;
245
246 enum gcry_cipher_algos {
247     GCRY_CIPHER_NONE        = 0,
248     GCRY_CIPHER_IDEA        = 1,
249     GCRY_CIPHER_3DES        = 2,
250     GCRY_CIPHER_CAST5       = 3,
251     GCRY_CIPHER_BLOWFISH    = 4,
252     GCRY_CIPHER_SAFER_SK128 = 5,
253     GCRY_CIPHER_DES_SK      = 6,
254     GCRY_CIPHER_TWOFISH     = 10,
255 };
256
257 enum gcry_cipher_modes {
258     GCRY_CIPHER_MODE_NONE   = 0,
259     GCRY_CIPHER_MODE_ECB    = 1,
260     GCRY_CIPHER_MODE_CFB    = 2,
261     GCRY_CIPHER_MODE_CBC    = 3,
262 };
263
264 enum gcry_cipher_flags {
265     GCRY_CIPHER_SECURE      = 1,  /* allocate in secure memory */
266     GCRY_CIPHER_ENABLE_SYNC = 2,  /* enable CFB sync mode */
267 };
268
269
270 GCRY_CIPHER_HD gcry_cipher_open( int algo, int mode, unsigned flags);
271 void gcry_cipher_close( GCRY_CIPHER_HD h );
272 int  gcry_cipher_ctl( GCRY_CIPHER_HD h, int cmd, void *buffer, size_t buflen);
273 int gcry_cipher_info( GCRY_CIPHER_HD h, int what, void *buffer, size_t *nbytes);
274 int gcry_cipher_algo_info( int algo, int what, void *buffer, size_t *nbytes);
275 const char *gcry_cipher_algo_name( int algo );
276 int gcry_cipher_map_name( const char* name );
277
278 int gcry_cipher_encrypt( GCRY_CIPHER_HD h, byte *out, size_t outsize,
279                                       const byte *in, size_t inlen );
280 int gcry_cipher_decrypt( GCRY_CIPHER_HD h, byte *out, size_t outsize,
281                                       const byte *in, size_t inlen );
282
283
284 /* some handy macros */
285 #define gcry_cipher_setkey(h,k,l)  gcry_cipher_ctl( (h), GCRYCTL_SET_KEY, \
286                                                                   (k), (l) )
287 #define gcry_cipher_setiv(h,k,l)  gcry_cipher_ctl( (h), GCRYCTL_SET_IV, \
288                                                                   (k), (l) )
289 #define gcry_cipher_sync(h)  gcry_cipher_ctl( (h), GCRYCTL_CFB_SYNC, \
290                                                                    NULL, 0 )
291
292 #define gcry_cipher_get_algo_keylen(a) \
293             gcry_cipher_algo_info( (a), GCRYCTL_GET_KEYLEN, NULL, NULL )
294 #define gcry_cipher_get_algo_blklen(a) \
295             gcry_cipher_algo_info( (a), GCRYCTL_GET_BLKLEN, NULL, NULL )
296 #define gcry_cipher_test_algo(a) \
297             gcry_cipher_algo_info( (a), GCRYCTL_TEST_ALGO, NULL, NULL )
298
299
300 /*********************************************
301  *******  asymmetric cipher functions  *******
302  *********************************************/
303
304 enum gcry_pk_algos {
305     GCRY_PK_RSA = 1,
306     GCRY_PK_RSA_E = 2,      /* use only for OpenPGP */
307     GCRY_PK_RSA_S = 3,      /* use only for OpenPGP */
308     GCRY_PK_ELG_E = 16,     /* use only for OpenPGP */
309     GCRY_PK_DSA   = 17,
310     GCRY_PK_ELG   = 20,
311 };
312
313 /* Flags describing usage capabilites/request of a PK algorithm */
314 #define GCRY_PK_USAGE_SIGN 1
315 #define GCRY_PK_USAGE_ENCR 2
316
317 int gcry_pk_encrypt( GCRY_SEXP *result, GCRY_SEXP data, GCRY_SEXP pkey );
318 int gcry_pk_decrypt( GCRY_SEXP *result, GCRY_SEXP data, GCRY_SEXP skey );
319 int gcry_pk_sign(    GCRY_SEXP *result, GCRY_SEXP data, GCRY_SEXP skey );
320 int gcry_pk_verify(  GCRY_SEXP sigval, GCRY_SEXP data, GCRY_SEXP pkey );
321
322 int gcry_pk_ctl( int cmd, void *buffer, size_t buflen);
323 int gcry_pk_algo_info( int algo, int what, void *buffer, size_t *nbytes);
324 const char *gcry_pk_algo_name( int algo );
325 int gcry_pk_map_name( const char* name );
326
327
328 #define gcry_pk_test_algo(a) \
329             gcry_pk_algo_info( (a), GCRYCTL_TEST_ALGO, NULL, NULL )
330
331 /*********************************************
332  *******  cryptograhic hash functions  *******
333  *********************************************/
334
335 enum gcry_md_algos {
336     GCRY_MD_NONE    = 0,
337     GCRY_MD_MD5     = 1,
338     GCRY_MD_SHA1    = 2,
339     GCRY_MD_RMD160  = 3,
340     GCRY_MD_TIGER   = 6
341 };
342
343 enum gcry_md_flags {
344     GCRY_MD_FLAG_SECURE = 1
345 };
346
347
348 struct gcry_md_context;
349 struct gcry_md_handle {
350     struct gcry_md_context *ctx;
351     int  bufpos;
352     int  bufsize;
353     byte buf[1];
354 };
355 typedef struct gcry_md_handle *GCRY_MD_HD;
356
357
358 GCRY_MD_HD gcry_md_open( int algo, unsigned flags );
359 void gcry_md_close( GCRY_MD_HD hd );
360 int gcry_md_enable( GCRY_MD_HD hd, int algo );
361 GCRY_MD_HD gcry_md_copy( GCRY_MD_HD hd );
362 void gcry_md_reset( GCRY_MD_HD hd );
363 int gcry_md_ctl( GCRY_MD_HD hd, int cmd, byte *buffer, size_t buflen);
364 void gcry_md_write( GCRY_MD_HD hd, const byte *buffer, size_t length);
365 byte *gcry_md_read( GCRY_MD_HD hd, int algo );
366 void gcry_md_hash_buffer( int algo, char *digest,
367                           const char *buffer, size_t length);
368 int gcry_md_get_algo( GCRY_MD_HD hd );
369 unsigned int gcry_md_get_algo_dlen( int algo );
370 /*??int gcry_md_get( GCRY_MD_HD hd, int algo, byte *buffer, int buflen );*/
371 int gcry_md_info( GCRY_MD_HD h, int what, void *buffer, size_t *nbytes);
372 int gcry_md_algo_info( int algo, int what, void *buffer, size_t *nbytes);
373 const char *gcry_md_algo_name( int algo );
374 int gcry_md_map_name( const char* name );
375
376 #define gcry_md_putc(h,c)  \
377             do {                                        \
378                 if( (h)->bufpos == (h)->bufsize )       \
379                     gcry_md_write( (h), NULL, 0 );      \
380                 (h)->buf[(h)->bufpos++] = (c) & 0xff;   \
381             } while(0)
382
383 #define gcry_md_final(a) \
384             gcry_md_ctl( (a), GCRYCTL_FINALIZE, NULL, 0 )
385
386 #define gcry_md_is_secure(a) \
387             gcry_md_info( (a), GCRYCTL_IS_SECURE, NULL, NULL )
388
389 #define gcry_md_test_algo(a) \
390             gcry_md_algo_info( (a), GCRYCTL_TEST_ALGO, NULL, NULL )
391
392 /*********************************************
393  *******  random generating functions  *******
394  *********************************************/
395 void gcry_randomize( byte *buffer, size_t length,
396                      enum gcry_random_level level );
397 void *gcry_random_bytes( size_t nbytes, enum gcry_random_level level );
398 void *gcry_random_bytes_secure( size_t nbytes, enum gcry_random_level level );
399
400 /*****************************************
401  *******  miscellaneous stuff   **********
402  *****************************************/
403
404 enum gcry_log_levels {
405     GCRY_LOG_CONT   = 0,    /* continue the last log line */
406     GCRY_LOG_INFO   = 10,
407     GCRY_LOG_WARN   = 20,
408     GCRY_LOG_ERROR  = 30,
409     GCRY_LOG_FATAL  = 40,
410     GCRY_LOG_BUG    = 50,
411     GCRY_LOG_DEBUG  = 100,
412 };
413
414
415 /* Provide custom functions for special tasks of libgcrypt.
416  */
417 void gcry_set_allocation_handler( void *(*new_alloc_func)(size_t n),
418                                   void *(*new_alloc_secure_func)(size_t n),
419                                   int (*new_is_secure_func)(const void*),
420                                   void *(*new_realloc_func)(void *p, size_t n),
421                                   void (*new_free_func)(void*) );
422 void gcry_set_outofcore_handler( int (*h)( void*, size_t, unsigned int ),
423                                                                 void *opaque );
424 void gcry_set_fatalerror_handler( void (*fnc)(void*,int, const char*),
425                                                                 void *opaque );
426 void gcry_set_gettext_handler( const char *(*f)(const char*) );
427 void gcry_set_log_handler( void (*f)(void*,int, const char*, va_list ),
428                                                              void *opaque );
429
430
431 /* Access to the memory function of libgcrypt.
432  * Especially the gcry_free() should be used for memory
433  * allocated by gcry_ functions.
434  */
435 void *gcry_malloc( size_t n );
436 void *gcry_calloc( size_t n, size_t m );
437 void *gcry_malloc_secure( size_t n );
438 void *gcry_calloc_secure( size_t n, size_t m );
439 void *gcry_realloc( void *a, size_t n );
440 void *gcry_xmalloc( size_t n );
441 void *gcry_xcalloc( size_t n, size_t m );
442 void *gcry_xmalloc_secure( size_t n );
443 void *gcry_xcalloc_secure( size_t n, size_t m );
444 void *gcry_xrealloc( void *a, size_t n );
445 char *gcry_xstrdup( const char * a);
446 void  gcry_free( void *p );
447
448
449 #ifndef GCRYPT_NO_MPI_MACROS
450 # ifndef DID_MPI_TYPEDEF
451     typedef struct gcry_mpi *MPI;
452 #   define DID_MPI_TYPEDEF
453 # endif
454 #endif /* GCRYPT_NO_MPI_MACROS */
455
456 #ifdef __cplusplus
457 }
458 #endif
459 #endif /* _GCRYPT_H */