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