* ath.c: Include sys.time.h if sys/select.h does not exist.
[libgcrypt.git] / src / gcrypt.h
1 /* gcrypt.h -  GNU cryptographic library interface
2  * Copyright (C) 1998,1999,2000,2001,2002 Free Software Foundation, Inc.
3  *
4  * This file is part of Libgcrypt.
5  *
6  * Libgcrypt is free software; you can redistribute it and/or modify
7  * it under the terms of the GNU Lesser General Public License as
8  * published by the Free Software Foundation; either version 2.1 of
9  * the License, or (at your option) any later version.
10  *
11  * Libgcrypt 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 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 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 #include <string.h>
26
27 #ifdef __cplusplus
28 extern "C" {
29 #if 0 /* keep Emacsens's auto-indent happy */
30 }
31 #endif
32 #endif
33
34 /* The version of this header should match the one of the library It
35    should not be used by a program because gcry_check_version() should
36    reurn the same version.  The purpose of this macro is to let
37    autoconf (using the AM_PATH_GCRYPT macro) check that this header
38    matches the installed library.  Note: Do not edit the next line as
39    configure may fix the string here.  */
40 #define GCRYPT_VERSION "1.1.10"
41
42 /* Internal: We can't to use the convenience macros for the multi
43    precision integer functions when building this library. */
44 #ifdef _GCRYPT_IN_LIBGCRYPT
45 # ifndef GCRYPT_NO_MPI_MACROS
46 #   define GCRYPT_NO_MPI_MACROS 1
47 # endif
48 #endif
49
50 /* The data object used to hold a multi precision integer.  GcryMPI is
51    the preferred one. */
52 struct gcry_mpi;
53 typedef struct gcry_mpi *GCRY_MPI;
54 typedef struct gcry_mpi *GcryMPI;
55
56 \f
57 /* Error handling etc. */
58
59 /* The error numbers used by Libgcrypt. */
60 /* FIXME: We should use the same values as they were used in GnuPG
61    1.0.  gpg --status-fd may print some of these values. */
62 enum
63   {
64     GCRYERR_SUCCESS = 0,    /* "no error" */
65     GCRYERR_GENERAL = 1,    /* catch all the other errors code */
66     
67     GCRYERR_INV_PK_ALGO = 4, /* invalid public key algorithm */
68     GCRYERR_INV_MD_ALGO = 5, /* invalid message digest algorithm */
69     GCRYERR_BAD_PUBLIC_KEY = 6, /* Bad public key */
70     GCRYERR_BAD_SECRET_KEY = 7, /* Bad secret key */
71     GCRYERR_BAD_SIGNATURE = 8,  /* Bad signature */
72     
73     GCRYERR_INV_CIPHER_ALGO = 12, /* invalid cipher algorithm */
74     GCRYERR_BAD_MPI = 30,
75     GCRYERR_WRONG_PK_ALGO = 41, /* wrong public key algorithm */
76     GCRYERR_WEAK_KEY = 43,  /* weak encryption key */
77     GCRYERR_INV_KEYLEN = 44,  /* invalid length of a key*/
78     GCRYERR_INV_ARG = 45,    /* invalid argument */
79     GCRYERR_SELFTEST = 50,      /* selftest failed */
80
81     /* error codes not used in GnuPG 1.0 */
82     GCRYERR_INV_OP = 61,     /* invalid operation code or ctl command */
83     GCRYERR_NO_MEM = 62,     /* out of core */
84     GCRYERR_INTERNAL = 63,   /* internal error */
85     GCRYERR_EOF = 64,        /* (-1) is remapped to this value */
86     GCRYERR_INV_OBJ = 65,    /* an object is not valid */
87     GCRYERR_TOO_SHORT = 66,  /* provided buffer too short */
88     GCRYERR_TOO_LARGE = 67,  /* object is too large */
89     GCRYERR_NO_OBJ = 68,     /* Missing item in an object */
90     GCRYERR_NOT_IMPL = 69,   /* Not implemented */
91     GCRYERR_CONFLICT = 70,
92     GCRYERR_INV_CIPHER_MODE = 71,
93
94     /* error codes pertaining to S-expressions */
95     GCRYERR_SEXP_INV_LEN_SPEC    = 201,
96     GCRYERR_SEXP_STRING_TOO_LONG = 202,
97     GCRYERR_SEXP_UNMATCHED_PAREN = 203, 
98     GCRYERR_SEXP_NOT_CANONICAL   = 204, 
99     GCRYERR_SEXP_BAD_CHARACTER   = 205, 
100     GCRYERR_SEXP_BAD_QUOTATION   = 206,/* or invalid hex or octal value */
101     GCRYERR_SEXP_ZERO_PREFIX     = 207,/* first character of a length is 0 */
102     GCRYERR_SEXP_NESTED_DH       = 208,/* nested display hints */
103     GCRYERR_SEXP_UNMATCHED_DH    = 209,/* unmatched display hint */
104     GCRYERR_SEXP_UNEXPECTED_PUNC = 210,/* unexpected reserved punctuation */
105     GCRYERR_SEXP_BAD_HEX_CHAR    = 211,
106     GCRYERR_SEXP_ODD_HEX_NUMBERS = 212,
107     GCRYERR_SEXP_BAD_OCT_CHAR    = 213
108   };
109
110 /* Check that the library fulfills the version requirement.  */
111 const char *gcry_check_version (const char *req_version);
112
113 /* Return the error number for the last failed function call. */
114 int gcry_errno(void);
115
116 /* Map an error number to a string. */
117 const char *gcry_strerror (int ec);
118
119 /* Codes used with the gcry_control function. */
120 enum gcry_ctl_cmds 
121   {
122     GCRYCTL_SET_KEY  = 1,
123     GCRYCTL_SET_IV   = 2,
124     GCRYCTL_CFB_SYNC = 3,
125     GCRYCTL_RESET    = 4,   /* e.g. for MDs */
126     GCRYCTL_FINALIZE = 5,
127     GCRYCTL_GET_KEYLEN = 6,
128     GCRYCTL_GET_BLKLEN = 7,
129     GCRYCTL_TEST_ALGO = 8,
130     GCRYCTL_IS_SECURE = 9,
131     GCRYCTL_GET_ASNOID = 10,
132     GCRYCTL_ENABLE_ALGO = 11,
133     GCRYCTL_DISABLE_ALGO = 12,
134     GCRYCTL_DUMP_RANDOM_STATS = 13,
135     GCRYCTL_DUMP_SECMEM_STATS = 14,
136     GCRYCTL_GET_ALGO_NPKEY    = 15,
137     GCRYCTL_GET_ALGO_NSKEY    = 16,
138     GCRYCTL_GET_ALGO_NSIGN    = 17,
139     GCRYCTL_GET_ALGO_NENCR    = 18,
140     GCRYCTL_SET_VERBOSITY     = 19,
141     GCRYCTL_SET_DEBUG_FLAGS   = 20,
142     GCRYCTL_CLEAR_DEBUG_FLAGS = 21,
143     GCRYCTL_USE_SECURE_RNDPOOL= 22,
144     GCRYCTL_DUMP_MEMORY_STATS = 23,
145     GCRYCTL_INIT_SECMEM       = 24,
146     GCRYCTL_TERM_SECMEM       = 25,
147     GCRYCTL_DISABLE_SECMEM_WARN = 27,
148     GCRYCTL_SUSPEND_SECMEM_WARN = 28,
149     GCRYCTL_RESUME_SECMEM_WARN  = 29,
150     GCRYCTL_DROP_PRIVS          = 30,
151     GCRYCTL_ENABLE_M_GUARD      = 31,
152     GCRYCTL_START_DUMP          = 32,
153     GCRYCTL_STOP_DUMP           = 33,
154     GCRYCTL_GET_ALGO_USAGE      = 34,
155     GCRYCTL_IS_ALGO_ENABLED     = 35,
156     GCRYCTL_DISABLE_INTERNAL_LOCKING = 36,
157     GCRYCTL_DISABLE_SECMEM      = 37,
158     GCRYCTL_INITIALIZATION_FINISHED = 38,
159     GCRYCTL_INITIALIZATION_FINISHED_P = 39,
160     GCRYCTL_ANY_INITIALIZATION_P = 40
161   };
162
163 /* Perform various operations defined by CMD. */
164 int gcry_control (enum gcry_ctl_cmds CMD, ...);
165
166
167 \f
168 /* S-expression management. */ 
169
170 /* The object to represent an S-expression as used with the
171    public key functions.  GcrySexp is the preferrred form. */
172 struct gcry_sexp;
173 typedef struct gcry_sexp *GCRY_SEXP;
174 typedef struct gcry_sexp *GcrySexp;  
175
176 /* The possible values for the S-expression format. */
177 enum gcry_sexp_format {
178     GCRYSEXP_FMT_DEFAULT   = 0,
179     GCRYSEXP_FMT_CANON     = 1,
180     GCRYSEXP_FMT_BASE64    = 2,
181     GCRYSEXP_FMT_ADVANCED  = 3
182 };
183
184 /* Create an new S-expression object from BUFFER of size LENGTH and
185    return it in RETSEXP.  With AUTODETECT set to 0 the data in BUFFER
186    is expected to be in canonized format */
187 int gcry_sexp_new (GcrySexp *retsexp, const void *buffer, size_t length,
188                    int autodetect);
189
190 /* Same as gcry_sexp_new but allows to pass a FREEFNC which has the
191    effect to transfer ownership of BUFFER to the created object. */
192 int gcry_sexp_create (GcrySexp *retsexp, void *buffer, size_t length,
193                       int autodetect, void (*freefnc)(void*) );
194
195 /* Scan BUFFER and return a new S-expression object in RETSEXP.  This
196    function expects a printf like string in BUFFER. */
197 int gcry_sexp_sscan (GcrySexp *retsexp, size_t *erroff,
198                      const char *buffer, size_t length );
199
200 /* Same as gcry_sexp_sscan but expects a string in FORMAT and can thus
201    only be used for certain encodings. */
202 int gcry_sexp_build (GcrySexp *retsexp, size_t *erroff,
203                      const char *format, ... );
204
205 /* Release the S-expression object SEXP */
206 void gcry_sexp_release (GcrySexp sexp);
207
208 /* Calculate the length of an canonized S-expresion in BUFFER and
209    check for a valid encoding. */
210 size_t gcry_sexp_canon_len (const unsigned char *buffer, size_t length, 
211                             size_t *erroff, int *errcode);
212
213 /* Copies the S-expression object SEXP into BUFFER using the format
214    specified in MODE. */
215 size_t gcry_sexp_sprint (GCRY_SEXP sexp, int mode, char *buffer,
216                          size_t maxlength );
217
218 void      gcry_sexp_dump( const GCRY_SEXP a );
219 GCRY_SEXP gcry_sexp_cons( const GCRY_SEXP a, const GCRY_SEXP b );
220 GCRY_SEXP gcry_sexp_alist( const GCRY_SEXP *array );
221 GCRY_SEXP gcry_sexp_vlist( const GCRY_SEXP a, ... );
222 GCRY_SEXP gcry_sexp_append( const GCRY_SEXP a, const GCRY_SEXP n );
223 GCRY_SEXP gcry_sexp_prepend( const GCRY_SEXP a, const GCRY_SEXP n );
224 GCRY_SEXP gcry_sexp_find_token( GCRY_SEXP list,
225                                   const char *tok, size_t toklen );
226 int         gcry_sexp_length( const GCRY_SEXP list );
227 GCRY_SEXP   gcry_sexp_nth( const GCRY_SEXP list, int number );
228 GCRY_SEXP   gcry_sexp_car( const GCRY_SEXP list );
229 GCRY_SEXP   gcry_sexp_cdr( const GCRY_SEXP list );
230 GCRY_SEXP   gcry_sexp_cadr( const GCRY_SEXP list );
231 const char *gcry_sexp_nth_data( const GCRY_SEXP list, int number,
232                                                       size_t *datalen );
233 GCRY_MPI    gcry_sexp_nth_mpi( GCRY_SEXP list, int number, int mpifmt );
234
235
236 \f
237 /*******************************************
238  *                                         *
239  *  multi precision integer functions      *
240  *                                         *
241  *******************************************/
242
243 /* Different formats of external big integer representation. */
244 enum gcry_mpi_format 
245   {
246     GCRYMPI_FMT_NONE= 0,
247     GCRYMPI_FMT_STD = 1,    /* twos complement stored without length */
248     GCRYMPI_FMT_PGP = 2,    /* As used by OpenPGP (only defined as unsigned)*/
249     GCRYMPI_FMT_SSH = 3,    /* As used by SSH (same as 1 but with length)*/
250     GCRYMPI_FMT_HEX = 4,    /* hex format */
251     GCRYMPI_FMT_USG = 5     /* like STD but this is an unsigned one */
252   };
253
254 /* Flags used for creating big integers.  */
255 enum gcry_mpi_flag 
256   {
257     GCRYMPI_FLAG_SECURE = 1,  /* Allocate the number in "secure" memory. */
258     GCRYMPI_FLAG_OPAQUE = 2   /* The number is not a real one but just a
259                                way to store some bytes.  This is
260                                useful for encrypted big integers. */
261   };
262
263
264 /* Allocate a new big integer object, initialize it with 0 and
265    initially allocate memory for a number of at least NBITS. */
266 GcryMPI gcry_mpi_new (unsigned int nbits);
267
268 /* Same as gcry_mpi_new() but allocate in "secure" memory. */
269 GcryMPI gcry_mpi_snew (unsigned int nbits);
270
271 /* Release the number A and free all associated resources. */
272 void gcry_mpi_release (GcryMPI a);
273
274 /* Create a new number with the same value as A. */
275 GcryMPI gcry_mpi_copy (const GcryMPI a);
276
277 /* Store the big integer value U in W. */
278 GcryMPI gcry_mpi_set (GcryMPI w, const GcryMPI u);
279
280 /* Store the unsigned integer value U in W. */
281 GcryMPI gcry_mpi_set_ui (GcryMPI w, unsigned long u);
282
283 /* Swap the values of A and B. */
284 void gcry_mpi_swap (GcryMPI a, GcryMPI b);
285
286 /* Compare the big integer number U and V returning 0 for equality, a
287    positive value for U > V and a negative for U < V. */
288 int gcry_mpi_cmp (const GcryMPI u, const GcryMPI v);
289
290 /* Compare the big integer number U with the unsigned integer V
291    returning 0 for equality, a positive value for U > V and a negative
292    for U < V. */
293 int gcry_mpi_cmp_ui (const GcryMPI u, unsigned long v);
294
295 /* Convert the external representation of an integer stored in BUFFER
296    with a size of (*NBYTES) in a newly create MPI returned in RET_MPI.
297    For certain formats a length is not required and may be passed as
298    NULL.  After a successful operation NBYTES received the number of
299    bytes actually scanned. */
300 int gcry_mpi_scan (GcryMPI *ret_mpi, enum gcry_mpi_format format,
301                    const char *buffer, size_t *nbytes);
302
303 /* Convert the big integer A into the external representation
304    described by FORMAT and store it in the provided BUFFER which has
305    the size (*NBYTES).  NBYTES receives the actual length of the
306    external representation. */
307 int gcry_mpi_print (enum gcry_mpi_format format,
308                     char *buffer, size_t *nbytes, const GcryMPI a);
309
310 /* Convert the big integer A int the external representation desribed
311    by FORMAT and store it in a newly allocated buffer which address
312    will be put into BUFFER.  NBYTES receives the actual lengths of the
313    external representation. */
314 int gcry_mpi_aprint (enum gcry_mpi_format format,
315                      void **buffer, size_t *nbytes, const GcryMPI a);
316
317 /* W = U + V.  */
318 void gcry_mpi_add (GcryMPI w, GcryMPI u, GcryMPI v);
319
320 /* W = U + V.  V is an unsigned integer. */
321 void gcry_mpi_add_ui (GcryMPI w, GcryMPI u, unsigned long v);
322
323 /* W = U + V mod M. */
324 void gcry_mpi_addm (GcryMPI w, GcryMPI u, GcryMPI v, GcryMPI m);
325
326 /* W = U - V. */
327 void gcry_mpi_sub (GcryMPI w, GcryMPI u, GcryMPI v);
328
329 /* W = U - V.  V is an unsigned integer. */
330 void gcry_mpi_sub_ui (GcryMPI w, GcryMPI u, unsigned long v );
331
332 /* W = U - V mod M */
333 void gcry_mpi_subm (GcryMPI w, GcryMPI u, GcryMPI v, GcryMPI m);
334
335 /* W = U * V. */
336 void gcry_mpi_mul (GcryMPI w, GcryMPI u, GcryMPI v);
337
338 /* W = U * V.  V is an unsigned integer. */
339 void gcry_mpi_mul_ui (GcryMPI w, GcryMPI u, unsigned long v );
340
341 /* W = U * V mod M. */
342 void gcry_mpi_mulm (GcryMPI w, GcryMPI u, GcryMPI v, GcryMPI m);
343
344 /* W = U * (2 ^ CNT). */
345 void gcry_mpi_mul_2exp (GcryMPI w, GcryMPI u, unsigned long cnt);
346
347 /* Q = DIVIDEND / DIVISOR, R = DIVIDEND % DIVISOR,
348    Q or R may be passed as NULL.  ROUND should be negative or 0. */
349 void gcry_mpi_div (GcryMPI q, GcryMPI r,
350                    GcryMPI dividend, GcryMPI divisor, int round);
351
352 /* R = DIVIDEND % DIVISOR */
353 void gcry_mpi_mod (GcryMPI r, GcryMPI dividend, GcryMPI divisor);
354
355 /* W = B ^ E mod M. */
356 void gcry_mpi_powm (GcryMPI w,
357                     const GcryMPI b, const GcryMPI e, const GcryMPI m);
358
359 /* Set G to the greatest common divisor of A and B.  
360    Return true if the G is 1. */
361 int gcry_mpi_gcd (GcryMPI g, GcryMPI a, GcryMPI b);
362
363 /* Set X to the multiplicative inverse of A mod M.
364    Return true if the value exists. */
365 int gcry_mpi_invm (GcryMPI x, GcryMPI a, GcryMPI m);
366
367
368 /* Return the number of bits required to represent A. */
369 unsigned int gcry_mpi_get_nbits (GcryMPI a);
370
371 /* Return true when bit number N (counting from 0) is set in A. */
372 int      gcry_mpi_test_bit (GcryMPI a, unsigned int n);
373
374 /* Set bit number N in A. */
375 void     gcry_mpi_set_bit (GcryMPI a, unsigned int n);
376
377 /* Clear bit number N in A. */
378 void     gcry_mpi_clear_bit (GcryMPI a, unsigned int n);
379
380 /* Set bit number N in A and clear all bits greater than N. */
381 void     gcry_mpi_set_highbit (GcryMPI a, unsigned int n);
382
383 /* Clear bit number N in A and all bits greater than N. */
384 void     gcry_mpi_clear_highbit (GcryMPI a, unsigned int n);
385
386 /* Shift the value of A by N bits to the right and store the result in X. */
387 void     gcry_mpi_rshift (GcryMPI x, GcryMPI a, unsigned int n);
388
389 /* Store NBITS of the value P points to in A and mark A as an opaque
390    value. */
391 GcryMPI gcry_mpi_set_opaque (GcryMPI a, void *p, unsigned int nbits);
392
393 /* creturn a pointer to an opaque value stored in A and return its
394    size in NBITS.  Note that the returned pointer is still owned by A
395    and that the function should never be used for an non-opaque
396    MPI. */
397 void *gcry_mpi_get_opaque (GcryMPI a, unsigned int *nbits);
398
399 /* Set the FLAG for the big integer A.  Currently only the flag
400    GCRYMPI_FLAG_SECURE is allowed to convert A into an big intger
401    stored in "secure" memory. */
402 void gcry_mpi_set_flag (GcryMPI a, enum gcry_mpi_flag flag);
403
404 /* Clear FLAG for the big integer A.  Note that this function is
405    currently useless as no flags are allowed. */
406 void gcry_mpi_clear_flag (GcryMPI a, enum gcry_mpi_flag flag);
407
408 /* Return true when the FLAG is set for A. */
409 int gcry_mpi_get_flag (GcryMPI a, enum gcry_mpi_flag flag);
410
411 /* Unless the GCRYPT_NO_MPI_MACROS is used, provide a couple of
412    convenience macors for the big integer functions. */
413 #ifndef GCRYPT_NO_MPI_MACROS
414 #define mpi_new(n)          gcry_mpi_new( (n) )
415 #define mpi_secure_new( n ) gcry_mpi_snew( (n) )
416 #define mpi_release( a )    do { gcry_mpi_release( (a) ); \
417                                  (a) = NULL; } while(0)
418 #define mpi_copy( a )       gcry_mpi_copy( (a) )
419 #define mpi_set( w, u)      gcry_mpi_set( (w), (u) )
420 #define mpi_set_ui( w, u)   gcry_mpi_set_ui( (w), (u) )
421 #define mpi_cmp( u, v )     gcry_mpi_cmp( (u), (v) )
422 #define mpi_cmp_ui( u, v )  gcry_mpi_cmp_ui( (u), (v) )
423
424 #define mpi_add_ui(w,u,v)   gcry_mpi_add_ui((w),(u),(v))
425 #define mpi_add(w,u,v)      gcry_mpi_add ((w),(u),(v))
426 #define mpi_addm(w,u,v,m)   gcry_mpi_addm ((w),(u),(v),(m))
427 #define mpi_sub_ui(w,u,v)   gcry_mpi_sub_ui ((w),(u),(v))
428 #define mpi_sub(w,u,v)      gcry_mpi_sub ((w),(u),(v))
429 #define mpi_subm(w,u,v,m)   gcry_mpi_subm ((w),(u),(v),(m))
430 #define mpi_mul_ui(w,u,v)   gcry_mpi_mul_ui ((w),(u),(v))
431 #define mpi_mul_2exp(w,u,v) gcry_mpi_mul_2exp ((w),(u),(v))
432 #define mpi_mul(w,u,v)      gcry_mpi_mul ((w),(u),(v))
433 #define mpi_mulm(w,u,v,m)   gcry_mpi_mulm ((w),(u),(v),(m))
434 #define mpi_powm(w,b,e,m)   gcry_mpi_powm ( (w), (b), (e), (m) )
435 #define mpi_tdiv(q,r,a,m)   gcry_mpi_div ( (q), (r), (a), (m), 0)
436 #define mpi_fdiv(q,r,a,m)   gcry_mpi_div ( (q), (r), (a), (m), -1)
437 #define mpi_mod(r,a,m)      gcry_mpi_mod ((r), (a), (m))
438 #define mpi_gcd(g,a,b)      gcry_mpi_gcd ( (g), (a), (b) )
439 #define mpi_invm(g,a,b)     gcry_mpi_invm ( (g), (a), (b) )
440
441 #define mpi_get_nbits(a)       gcry_mpi_get_nbits ((a))
442 #define mpi_test_bit(a,b)      gcry_mpi_test_bit ((a),(b))
443 #define mpi_set_bit(a,b)       gcry_mpi_set_bit ((a),(b))
444 #define mpi_set_highbit(a,b)   gcry_mpi_set_highbit ((a),(b))
445 #define mpi_clear_bit(a,b)     gcry_mpi_clear_bit ((a),(b))
446 #define mpi_clear_highbit(a,b) gcry_mpi_clear_highbit ((a),(b))
447 #define mpi_rshift(a,b,c)      gcry_mpi_rshift ((a),(b),(c))
448
449 #define mpi_set_opaque(a,b,c) gcry_mpi_set_opaque( (a), (b), (c) )
450 #define mpi_get_opaque(a,b)   gcry_mpi_get_opaque( (a), (b) )
451 #endif /* GCRYPT_NO_MPI_MACROS */
452
453
454 \f
455 /************************************
456  *                                  *
457  *   symmetric cipher functions     *
458  *                                  *
459  ************************************/
460
461 /* The data object used to hold a handle to an encryption opject.
462    GcryCipherHd is the preferred one. */
463 struct gcry_cipher_handle;
464 typedef struct gcry_cipher_handle *GCRY_CIPHER_HD;
465 typedef struct gcry_cipher_handle *GcryCipherHd;
466
467 /* All symmetric encryption algorithms are identified by their IDs.
468    More IDs may be registered at runtime. */
469 enum gcry_cipher_algos
470   {
471     GCRY_CIPHER_NONE        = 0,
472     GCRY_CIPHER_IDEA        = 1,
473     GCRY_CIPHER_3DES        = 2,
474     GCRY_CIPHER_CAST5       = 3,
475     GCRY_CIPHER_BLOWFISH    = 4,
476     GCRY_CIPHER_SAFER_SK128 = 5,
477     GCRY_CIPHER_DES_SK      = 6,
478     GCRY_CIPHER_AES         = 7,
479     GCRY_CIPHER_AES192      = 8,
480     GCRY_CIPHER_AES256      = 9,
481     GCRY_CIPHER_TWOFISH     = 10,
482     /* other cipher numbers are above 300 for OpenPGP reasons. */
483     GCRY_CIPHER_ARCFOUR     = 301,
484     GCRY_CIPHER_DES         = 302
485   };
486
487 /* The Rijndael algorithm is basically AES, so provide some macros. */
488 #define GCRY_CIPHER_AES128      GCRY_CIPHER_AES    
489 #define GCRY_CIPHER_RIJNDAEL    GCRY_CIPHER_AES    
490 #define GCRY_CIPHER_RIJNDAEL128 GCRY_CIPHER_AES128 
491 #define GCRY_CIPHER_RIJNDAEL192 GCRY_CIPHER_AES192 
492 #define GCRY_CIPHER_RIJNDAEL256 GCRY_CIPHER_AES256 
493
494 /* The supported encryption modes.  NOte that not all of them are
495    supported for each algorithm. */
496 enum gcry_cipher_modes 
497   {
498     GCRY_CIPHER_MODE_NONE   = 0,  /* Not yet specified. */
499     GCRY_CIPHER_MODE_ECB    = 1,  /* Electronic codebook. */
500     GCRY_CIPHER_MODE_CFB    = 2,  /* Cipher feedback. */
501     GCRY_CIPHER_MODE_CBC    = 3,  /* Cipher block chaining. */
502     GCRY_CIPHER_MODE_STREAM = 4,  /* Used with stream ciphers. */
503     GCRY_CIPHER_MODE_OFB    = 5   /* Outer feedback. */
504   };
505
506 /* Flags used with the open function. */ 
507 enum gcry_cipher_flags
508   {
509     GCRY_CIPHER_SECURE      = 1,  /* Allocate in secure memory. */
510     GCRY_CIPHER_ENABLE_SYNC = 2   /* Enable CFB sync mode. */
511   };
512
513
514 /* Create a handle for algorithm ALGO to be used in MODE.  FLAGS may
515    be given as an bitwise OR of the gcry_cipher_flags values. */
516 GcryCipherHd gcry_cipher_open (int algo, int mode, unsigned int flags);
517
518 /* Close the cioher handle H and release all resource. */
519 void gcry_cipher_close (GcryCipherHd h);
520
521 /* Perform various operations on the cipher object H. */
522 int gcry_cipher_ctl( GcryCipherHd h, int cmd, void *buffer, size_t buflen);
523
524 /* Retrieve various information about the cipher object H. */
525 int gcry_cipher_info( GcryCipherHd h, int what, void *buffer, size_t *nbytes);
526
527 /* Retrieve various information about the cipher algorithm ALGO. */
528 int gcry_cipher_algo_info (int algo, int what, void *buffer, size_t *nbytes);
529
530 /* Map the cipher algorithm id ALGO to a string representation of that
531    algorithm name.  For unknown algorithms this functions returns an
532    empty string. */
533 const char *gcry_cipher_algo_name (int algo);
534
535 /* Map the algorithm name NAME to an cipher algorithm ID.  Return 0 if
536    the algorithm name is not known. */
537 int gcry_cipher_map_name (const char *name);
538
539 /* Given an ASN.1 object identifier in standard IETF dotted decimal
540    format in STING, return the encryption mode associated with that
541    OID or 0 if not known or applicable. */
542 int gcry_cipher_mode_from_oid (const char *string);
543
544 /* Encrypt the plaintext of size INLEN in IN using the cipher handle H
545    into the buffer OUT which has an allocated length of OUTSIZE.  For
546    most algorithms it is possible to pass NULL for in and 0 for INLEN
547    and do a in-place decryption of the data provided in OUT. */
548 int gcry_cipher_encrypt (GcryCipherHd h,
549                          unsigned char *out, size_t outsize,
550                          const unsigned char *in, size_t inlen);
551
552 /* The counterpart to gcry_cipher_encrypt. */
553 int gcry_cipher_decrypt (GcryCipherHd h,
554                          unsigned char *out, size_t outsize,
555                          const unsigned char *in, size_t inlen);
556
557 /* Set key K of length L for the cipher handle H. 
558   (We have to cast away a const char* here - this catch-all ctl
559   function was probably not the best choice) */
560 #define gcry_cipher_setkey(h,k,l)  gcry_cipher_ctl( (h), GCRYCTL_SET_KEY, \
561                                                          (char*)(k), (l) )
562
563 /* Set initialization vector K of length L for the cipher handle H. */
564 #define gcry_cipher_setiv(h,k,l)  gcry_cipher_ctl( (h), GCRYCTL_SET_IV, \
565                                                          (char*)(k), (l) )
566
567 /* Perform the the OppenPGP sync operation if this is enabled for the
568    cipher handle H. */
569 #define gcry_cipher_sync(h)  gcry_cipher_ctl( (h), GCRYCTL_CFB_SYNC, \
570                                                                    NULL, 0 )
571
572 /* Retrieved the key length used with algorithm A. */
573 #define gcry_cipher_get_algo_keylen(a) \
574             gcry_cipher_algo_info( (a), GCRYCTL_GET_KEYLEN, NULL, NULL )
575
576 /* Retrieve the block length used with algorithm A. */
577 #define gcry_cipher_get_algo_blklen(a) \
578             gcry_cipher_algo_info( (a), GCRYCTL_GET_BLKLEN, NULL, NULL )
579
580 /* Return 0 if the algorithm A is available for use. */
581 #define gcry_cipher_test_algo(a) \
582             gcry_cipher_algo_info( (a), GCRYCTL_TEST_ALGO, NULL, NULL )
583
584
585 \f
586 /************************************
587  *                                  *
588  *    asymmetric cipher functions   *
589  *                                  *
590  ************************************/
591
592 /* The algorithms and their IDs we support. */
593 enum gcry_pk_algos 
594   {
595     GCRY_PK_RSA = 1,
596     GCRY_PK_RSA_E = 2,      /* deprecated */
597     GCRY_PK_RSA_S = 3,      /* deprecated */
598     GCRY_PK_ELG_E = 16,     /* use only for OpenPGP */
599     GCRY_PK_DSA   = 17,
600     GCRY_PK_ELG   = 20
601   };
602
603 /* Flags describing usage capabilities of a PK algorithm. */
604 #define GCRY_PK_USAGE_SIGN 1
605 #define GCRY_PK_USAGE_ENCR 2
606
607 /* Encrypt the DATA using the public key PKEY and store the result as
608    a newly created S-expression at RESULT. */
609 int gcry_pk_encrypt (GcrySexp *result, GcrySexp data, GcrySexp pkey);
610
611 /* Decrypt the DATA using the private key SKEY and store the result as
612    a newly created S-expression at RESULT. */
613 int gcry_pk_decrypt (GcrySexp *result, GcrySexp data, GcrySexp skey);
614
615 /* Sign the DATA using the private key SKEY and store the result as
616    a newly created S-expression at RESULT. */
617 int gcry_pk_sign (GcrySexp *result, GcrySexp data, GcrySexp skey);
618
619 /* Check the signature SIGVAL on DATA using the public key PKEY. */
620 int gcry_pk_verify (GcrySexp sigval, GcrySexp data, GcrySexp pkey);
621
622 /* Check that KEY (either private or public) is sane. */
623 int gcry_pk_testkey (GcrySexp key);
624
625 /* Generate a new key pair according to the parameters given in
626    S_PARMS.  The new key pair is returned in as an S-expression in
627    R_KEY. */
628 int gcry_pk_genkey (GcrySexp *r_key, GcrySexp s_parms);
629
630 /* Catch all function for miscellaneous operations. */
631 int gcry_pk_ctl (int cmd, void *buffer, size_t buflen);
632
633 /* Retrieve information about the public key algorithm ALGO. */
634 int gcry_pk_algo_info (int algo, int what, void *buffer, size_t *nbytes);
635
636 /* Map the public key algorithm id ALGO to a string representation of the
637    algorithm name.  For unknown algorithms this functions returns an
638    empty string. */
639 const char *gcry_pk_algo_name (int algo);
640
641 /* Map the algorithm NAME to a public key algorithm Id.  Return 0 if
642    the algorithm name is not known. */
643 int gcry_pk_map_name (const char* name);
644
645 /* Return what is commonly referred as the key length for the given
646    public or private KEY.  */
647 unsigned int gcry_pk_get_nbits (GcrySexp key);
648
649 /* Please note that keygrip is still experimental and should not be
650    used without contacting the author. */
651 unsigned char *gcry_pk_get_keygrip (GcrySexp key, unsigned char *array);
652
653 /* Return 0 if the public key algorithm A is available for use. */
654 #define gcry_pk_test_algo(a) \
655             gcry_pk_algo_info( (a), GCRYCTL_TEST_ALGO, NULL, NULL )
656
657
658 \f
659 /************************************
660  *                                  *
661  *   cryptograhic hash functions    *
662  *                                  *
663  ************************************/
664
665 /* Algorithm IDs for the hash functions we know about. Not all of them
666    are implemnted. */
667 enum gcry_md_algos
668   {
669     GCRY_MD_NONE    = 0,  
670     GCRY_MD_MD5     = 1,
671     GCRY_MD_SHA1    = 2,
672     GCRY_MD_RMD160  = 3,
673     GCRY_MD_MD2     = 5,
674     GCRY_MD_TIGER   = 6,   /* TIGER/192. */
675     GCRY_MD_HAVAL   = 7,   /* HAVAL, 5 pass, 160 bit. */
676     GCRY_MD_SHA256  = 8,
677     GCRY_MD_SHA384  = 9,
678     GCRY_MD_SHA512  = 10
679   };
680
681 /* Flags used with the open function. */
682 enum gcry_md_flags
683   {
684     GCRY_MD_FLAG_SECURE = 1,  /* Allocate all buffers in "secure" memory */
685     GCRY_MD_FLAG_HMAC   = 2   /* Make an HMAC out of this algorithm. */
686   };
687
688
689 /* This object is used to hold a handle to an message digest object.
690    GcryCipherHd is the preferred type. */
691 struct gcry_md_context;
692 struct gcry_md_handle 
693   { /* This structure is private - only to be used by the gcry_md_  macros. */
694     struct gcry_md_context *ctx;
695     int  bufpos;
696     int  bufsize;
697     unsigned char buf[1];
698   };
699 typedef struct gcry_md_handle *GCRY_MD_HD;
700 typedef struct gcry_md_handle *GcryMDHd;
701
702
703 /* Create a message digest object for algorithm ALGO.  FLAGS may be
704    given as an bitwise OR of the gcry_md_flags values.  ALGO may be
705    given as 0 if the algorithms to used are later set using
706    gcry_md_enable. */
707 GcryMDHd gcry_md_open (int algo, unsigned int flags);
708
709 /* Release the message digest object HD. */
710 void gcry_md_close (GcryMDHd hd);
711
712 /* Add the message digest algorithm ALGO to the digest object HD. */
713 int gcry_md_enable( GcryMDHd hd, int algo );
714
715 /* Create a new digest object as an exact copy of the object HD. */
716 GcryMDHd gcry_md_copy (GcryMDHd hd);
717
718 /* Reset the digest object HD to its initail state. */
719 void gcry_md_reset (GcryMDHd hd);
720
721 /* Perform various operations on the digets object HD. */
722 int gcry_md_ctl (GcryMDHd hd, int cmd, unsigned char *buffer, size_t buflen);
723
724 /* Pass LENGTH bytes of data in BUFFER to the digest object HD so that
725    it can update the digest values.  This is the actual hash
726    function. */
727 void gcry_md_write (GcryMDHd hd, const unsigned char *buffer, size_t length);
728
729 /* Read out the final digest from HD return the digest value for
730    algorithm ALGO. */
731 unsigned char *gcry_md_read (GcryMDHd hd, int algo);
732
733 /* Convenience function to calculate the hash from the data in BUFFER
734    of size LENGTH using the algorithm ALGO avoiding the creating of a
735    hash object.  The hash is returned in the caller provied buffer
736    DIGEST which must be large enough to hold the digest of the given
737    algorithm. */
738 void gcry_md_hash_buffer (int algo, char *digest,
739                           const char *buffer, size_t length);
740
741 /* Retrieve the algorithm used with HD.  This does not work relaibale
742    if more than one algorithm is enabled in HD. */
743 int gcry_md_get_algo (GcryMDHd hd);
744
745 /* Retrieved the length in bytes of the digest yielded by algorithm
746    ALGO. */
747 unsigned int gcry_md_get_algo_dlen (int algo);
748
749 /* Retrieve various information about the obhject H. */
750 int gcry_md_info (GcryMDHd h, int what, void *buffer, size_t *nbytes);
751
752 /* Retrieve valrious information about the algorithm ALGO. */
753 int gcry_md_algo_info( int algo, int what, void *buffer, size_t *nbytes);
754
755 /* Map the digest algorithm id ALGO to a string representation of the
756    algorithm name.  For unknown algorithms this functions returns an
757    empty string. */
758 const char *gcry_md_algo_name (int algo);
759
760 /* Map the algorithm NAME to a digest algorithm Id.  Return 0 if
761    the algorithm name is not known. */
762 int gcry_md_map_name (const char* name);
763
764 /* For use with the HMAC feature, the set MAC key to the KEY of
765    KEYLEN. */
766 int gcry_md_setkey (GcryMDHd hd, const char *key, size_t keylen);
767
768 /* Update the hash(s) of H with the character C.  This is a buffered
769    version of the gcry_md_write function. */
770 #define gcry_md_putc(h,c)  \
771             do {                                        \
772                 if( (h)->bufpos == (h)->bufsize )       \
773                     gcry_md_write( (h), NULL, 0 );      \
774                 (h)->buf[(h)->bufpos++] = (c) & 0xff;   \
775             } while(0)
776
777 /* Finalize the digest calculation.  This is not really needed because
778    gcry_md_read() does this implicitly. */
779 #define gcry_md_final(a) \
780             gcry_md_ctl ((a), GCRYCTL_FINALIZE, NULL, 0)
781
782 /* Return true when the digest object is allocated in "secure" memory. */
783 #define gcry_md_is_secure(a) \
784             gcry_md_info( (a), GCRYCTL_IS_SECURE, NULL, NULL )
785
786 /* Return 0 if the algorithm A is available for use. */
787 #define gcry_md_test_algo(a) \
788             gcry_md_algo_info( (a), GCRYCTL_TEST_ALGO, NULL, NULL )
789
790 /* Enable debugging for digets object A; i.e. create files named
791    dbgmd-<n>.<string> while hashing.  B is a string used as the suffix
792    for the filename. */
793 #define gcry_md_start_debug(a,b) \
794             gcry_md_ctl( (a), GCRYCTL_START_DUMP, (b), 0 )
795
796 /* Disable the debugging of A. */
797 #define gcry_md_stop_debug(a,b) \
798             gcry_md_ctl( (a), GCRYCTL_STOP_DUMP, (b), 0 )
799
800
801 \f
802 /************************************
803  *                                  *
804  *   random generating functions    *
805  *                                  *
806  ************************************/
807
808 /* The possible values for the random quality.  The rule of thumb is
809    to use WEAK for random number which don't need to be
810    cryptographically strong, STRONG for session keys and VERY_STRONG
811    for key material. */
812 enum gcry_random_level
813   {
814     GCRY_WEAK_RANDOM = 0,
815     GCRY_STRONG_RANDOM = 1,
816     GCRY_VERY_STRONG_RANDOM = 2
817   };
818
819 /* Fill BUFFER with LENGTH bytes of random, using random numbers of
820    quality LEVEL. */
821 void gcry_randomize (unsigned char *buffer, size_t length,
822                      enum gcry_random_level level);
823
824 /* Return NBYTES of allocated random suing a radnom numbers of quality
825    LEVEL. */
826 void *gcry_random_bytes (size_t nbytes, enum gcry_random_level level);
827
828 /* Return NBYTES of allocated random suing a random numbers of quality
829    LEVEL.  The random numbers are created returned in "secure"
830    memory. */
831 void *gcry_random_bytes_secure (size_t nbytes, enum gcry_random_level level);
832
833
834 /* Set the big inetger W to a random value of NBITS using a random
835    generator with quality LEVEL. */
836 void gcry_mpi_randomize (GcryMPI w,
837                          unsigned int nbits, enum gcry_random_level level);
838
839
840 \f
841 /************************************
842  *                                  *
843  *     miscellaneous stuff          *
844  *                                  *
845  ************************************/
846
847 /* Log leveles used by the internal logging facility. */
848 enum gcry_log_levels 
849   {
850     GCRY_LOG_CONT   = 0,    /* continue the last log line */
851     GCRY_LOG_INFO   = 10,
852     GCRY_LOG_WARN   = 20,
853     GCRY_LOG_ERROR  = 30,
854     GCRY_LOG_FATAL  = 40,
855     GCRY_LOG_BUG    = 50,
856     GCRY_LOG_DEBUG  = 100
857   };
858
859
860 /* Certain operations can provide progress information.  This function
861    is used to register a handler for retrieving these information. */
862 void gcry_set_progress_handler (void (*cb)(void *,const char*,int, int, int),
863                                 void *cb_data);
864
865
866
867 /* Register a custom memory allocation functions. */
868 void gcry_set_allocation_handler (void *(*new_alloc_func)(size_t n),
869                                   void *(*new_alloc_secure_func)(size_t n),
870                                   int (*new_is_secure_func)(const void*),
871                                   void *(*new_realloc_func)(void *p, size_t n),
872                                   void (*new_free_func)(void*));
873
874 /* Register a function used instead of the internal out of memory
875    handler. */
876 void gcry_set_outofcore_handler (int (*h)(void*, size_t, unsigned int),
877                                  void *opaque );
878
879 /* Register a function used instead of the internal fatal error
880    handler. */
881 void gcry_set_fatalerror_handler (void (*fnc)(void*,int, const char*),
882                                   void *opaque);
883
884 /* Reserved for future use. */
885 void gcry_set_gettext_handler (const char *(*f)(const char*));
886
887 /* Regstier a function used instead of the internal logging
888    facility. */
889 void gcry_set_log_handler (void (*f)(void*,int, const char*, va_list),
890                            void *opaque);
891
892
893 /* Libgcrypt uses its own memory allocation.  It is important to use
894    gcry_free () to release memory allocated by libgcrypt. */
895 void *gcry_malloc (size_t n);
896 void *gcry_calloc (size_t n, size_t m);
897 void *gcry_malloc_secure (size_t n);
898 void *gcry_calloc_secure (size_t n, size_t m);
899 void *gcry_realloc (void *a, size_t n);
900 char *gcry_strdup (const char *string);
901 void *gcry_xmalloc (size_t n);
902 void *gcry_xcalloc (size_t n, size_t m);
903 void *gcry_xmalloc_secure (size_t n);
904 void *gcry_xcalloc_secure (size_t n, size_t m);
905 void *gcry_xrealloc (void *a, size_t n);
906 char *gcry_xstrdup (const char * a);
907 void  gcry_free (void *a);
908
909 /* Return true if A is allocated in "secure" memory. */
910 int gcry_is_secure (const void *a);
911
912
913 #ifndef GCRYPT_NO_MPI_MACROS
914 # ifndef DID_MPI_TYPEDEF
915     typedef struct gcry_mpi *MPI;
916 #   define DID_MPI_TYPEDEF
917 # endif
918 #endif /* GCRYPT_NO_MPI_MACROS */
919
920 #ifdef __cplusplus
921 }
922 #endif
923 #endif /* _GCRYPT_H */