2003-07-07 Moritz Schulte <moritz@g10code.com>
[libgcrypt.git] / src / gcrypt.h
1 /* gcrypt.h -  GNU cryptographic library interface
2  * Copyright (C) 1998,1999,2000,2001,2002,2003 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 #include <gpg-error.h>
28
29 /* This is required for error code compatibility. */
30 #define _GCRY_ERR_SOURCE_DEFAULT GPG_ERR_SOURCE_GCRYPT
31
32 #ifdef __cplusplus
33 extern "C" {
34 #if 0 /* keep Emacsens's auto-indent happy */
35 }
36 #endif
37 #endif
38
39 /* The version of this header should match the one of the library It
40    should not be used by a program because gcry_check_version() should
41    return the same version.  The purpose of this macro is to let
42    autoconf (using the AM_PATH_GCRYPT macro) check that this header
43    matches the installed library.  Note: Do not edit the next line as
44    configure may fix the string here.  */
45 #define GCRYPT_VERSION "1.1.13-cvs"
46
47 /* Internal: We can't use the convenience macros for the multi
48    precision integer functions when building this library. */
49 #ifdef _GCRYPT_IN_LIBGCRYPT
50 #ifndef GCRYPT_NO_MPI_MACROS
51 #define GCRYPT_NO_MPI_MACROS 1
52 #endif
53 #endif
54
55 /* We want to use gcc attributes when possible.  Warning: Don't use
56    these macros in your progranms: As indicated by the leading
57    underscore they are subject to change without notice. */
58 #ifdef __GNUC__
59
60 #define _GCRY_GCC_VERSION (__GNUC__ * 10000 \
61                              + __GNUC_MINOR__ * 100 \
62                              + __GNUC_PATCHLEVEL__)
63
64 #if _GCRY_GCC_VERSION >= 30100
65 #define _GCRY_GCC_ATTR_DEPRECATED __attribute__ ((__deprecated__))
66 #endif
67
68 #if _GCRY_GCC_VERSION >= 29600
69 #define _GCRY_GCC_ATTR_PURE  __attribute__ ((__pure__))
70 #endif
71
72 #if _GCRY_GCC_VERSION >= 300200
73 #define _GCRY_GCC_ATTR_MALLOC  __attribute__ ((__malloc__))
74 #endif
75
76 #endif
77
78 #ifndef _GCRY_GCC_ATTR_DEPRECATED
79 #define _GCRY_GCC_ATTR_DEPRECATED
80 #endif
81 #ifndef _GCRY_GCC_ATTR_PURE
82 #define _GCRY_GCC_ATTR_PURE
83 #endif
84 #ifndef _GCRY_GCC_ATTR_MALLOC
85 #define _GCRY_GCC_ATTR_MALLOC
86 #endif
87
88 /* The data object used to hold a multi precision integer.  */
89 struct gcry_mpi;
90 typedef struct gcry_mpi *gcry_mpi_t;
91
92 typedef struct gcry_mpi *GCRY_MPI _GCRY_GCC_ATTR_DEPRECATED;
93 typedef struct gcry_mpi *GcryMPI _GCRY_GCC_ATTR_DEPRECATED;
94
95 \f
96
97 /* This type represents a `module'.  */
98 typedef struct gcry_module *gcry_module_t;
99
100 /* Check that the library fulfills the version requirement.  */
101 const char *gcry_check_version (const char *req_version);
102
103 #if 0
104 /* FIXME.  */
105 /* Map an error number to a string. */
106 const char *gcry_strerror (gpg_error_t ec);
107 #endif
108
109 /* Codes for function dispatchers.  */
110
111 /* Codes used with the gcry_control function. */
112 enum gcry_ctl_cmds 
113   {
114     GCRYCTL_SET_KEY  = 1,
115     GCRYCTL_SET_IV   = 2,
116     GCRYCTL_CFB_SYNC = 3,
117     GCRYCTL_RESET    = 4,   /* e.g. for MDs */
118     GCRYCTL_FINALIZE = 5,
119     GCRYCTL_GET_KEYLEN = 6,
120     GCRYCTL_GET_BLKLEN = 7,
121     GCRYCTL_TEST_ALGO = 8,
122     GCRYCTL_IS_SECURE = 9,
123     GCRYCTL_GET_ASNOID = 10,
124     GCRYCTL_ENABLE_ALGO = 11,
125     GCRYCTL_DISABLE_ALGO = 12,
126     GCRYCTL_DUMP_RANDOM_STATS = 13,
127     GCRYCTL_DUMP_SECMEM_STATS = 14,
128     GCRYCTL_GET_ALGO_NPKEY    = 15,
129     GCRYCTL_GET_ALGO_NSKEY    = 16,
130     GCRYCTL_GET_ALGO_NSIGN    = 17,
131     GCRYCTL_GET_ALGO_NENCR    = 18,
132     GCRYCTL_SET_VERBOSITY     = 19,
133     GCRYCTL_SET_DEBUG_FLAGS   = 20,
134     GCRYCTL_CLEAR_DEBUG_FLAGS = 21,
135     GCRYCTL_USE_SECURE_RNDPOOL= 22,
136     GCRYCTL_DUMP_MEMORY_STATS = 23,
137     GCRYCTL_INIT_SECMEM       = 24,
138     GCRYCTL_TERM_SECMEM       = 25,
139     GCRYCTL_DISABLE_SECMEM_WARN = 27,
140     GCRYCTL_SUSPEND_SECMEM_WARN = 28,
141     GCRYCTL_RESUME_SECMEM_WARN  = 29,
142     GCRYCTL_DROP_PRIVS          = 30,
143     GCRYCTL_ENABLE_M_GUARD      = 31,
144     GCRYCTL_START_DUMP          = 32,
145     GCRYCTL_STOP_DUMP           = 33,
146     GCRYCTL_GET_ALGO_USAGE      = 34,
147     GCRYCTL_IS_ALGO_ENABLED     = 35,
148     GCRYCTL_DISABLE_INTERNAL_LOCKING = 36,
149     GCRYCTL_DISABLE_SECMEM      = 37,
150     GCRYCTL_INITIALIZATION_FINISHED = 38,
151     GCRYCTL_INITIALIZATION_FINISHED_P = 39,
152     GCRYCTL_ANY_INITIALIZATION_P = 40,
153     GCRYCTL_SET_CBC_CTS = 41,
154     GCRYCTL_SET_CBC_MAC = 42,
155     GCRYCTL_SET_CTR = 43,
156     GCRYCTL_ENABLE_QUICK_RANDOM = 44,
157   };
158
159 /* Perform various operations defined by CMD. */
160 gpg_error_t gcry_control (enum gcry_ctl_cmds CMD, ...);
161
162
163 \f
164 /* S-expression management. */ 
165
166 /* The object to represent an S-expression as used with the public key
167    functions.  */
168 struct gcry_sexp;
169 typedef struct gcry_sexp *gcry_sexp_t;
170
171 typedef struct gcry_sexp *GCRY_SEXP _GCRY_GCC_ATTR_DEPRECATED;
172 typedef struct gcry_sexp *GcrySexp _GCRY_GCC_ATTR_DEPRECATED;
173
174 /* The possible values for the S-expression format. */
175 enum gcry_sexp_format
176   {
177     GCRYSEXP_FMT_DEFAULT   = 0,
178     GCRYSEXP_FMT_CANON     = 1,
179     GCRYSEXP_FMT_BASE64    = 2,
180     GCRYSEXP_FMT_ADVANCED  = 3
181   };
182
183 /* Create an new S-expression object from BUFFER of size LENGTH and
184    return it in RETSEXP.  With AUTODETECT set to 0 the data in BUFFER
185    is expected to be in canonized format.  */
186 gpg_error_t gcry_sexp_new (gcry_sexp_t *retsexp, const void *buffer, size_t length,
187                            int autodetect);
188
189  /* Same as gcry_sexp_new but allows to pass a FREEFNC which has the
190    effect to transfer ownership of BUFFER to the created object.  */
191 gpg_error_t gcry_sexp_create (gcry_sexp_t *retsexp, void *buffer, size_t length,
192                               int autodetect, void (*freefnc) (void *));
193
194 /* Scan BUFFER and return a new S-expression object in RETSEXP.  This
195    function expects a printf like string in BUFFER.  */
196 gpg_error_t gcry_sexp_sscan (gcry_sexp_t *retsexp, size_t *erroff,
197                              const char *buffer, size_t length);
198
199 /* Same as gcry_sexp_sscan but expects a string in FORMAT and can thus
200    only be used for certain encodings.  */
201 gpg_error_t gcry_sexp_build (gcry_sexp_t *retsexp, size_t *erroff,
202                              const char *format, ...);
203
204 /* Like gcry_sexp_build, but uses an array instead of variable
205    function arguments.  */
206 gpg_error_t gcry_sexp_build_array (gcry_sexp_t *retsexp, size_t *erroff,
207                                    const char *format, void **arg_list);
208
209 /* Release the S-expression object SEXP */
210 void gcry_sexp_release (gcry_sexp_t sexp);
211
212 /* Calculate the length of an canonized S-expresion in BUFFER and
213    check for a valid encoding. */
214 size_t gcry_sexp_canon_len (const unsigned char *buffer, size_t length, 
215                             size_t *erroff, gpg_error_t *errcode);
216
217 /* Copies the S-expression object SEXP into BUFFER using the format
218    specified in MODE.  */
219 size_t gcry_sexp_sprint (gcry_sexp_t sexp, int mode, char *buffer,
220                          size_t maxlength);
221
222 /* Dumps the S-expression object A in a aformat suitable for debugging
223    to Libgcrypt's logging stream.  */
224 void gcry_sexp_dump (const gcry_sexp_t a);
225
226 gcry_sexp_t gcry_sexp_cons (const gcry_sexp_t a, const gcry_sexp_t b);
227 gcry_sexp_t gcry_sexp_alist (const gcry_sexp_t *array);
228 gcry_sexp_t gcry_sexp_vlist (const gcry_sexp_t a, ...);
229 gcry_sexp_t gcry_sexp_append (const gcry_sexp_t a, const gcry_sexp_t n);
230 gcry_sexp_t gcry_sexp_prepend (const gcry_sexp_t a, const gcry_sexp_t n);
231
232 /* Scan the S-expression for a sublist with a type (the car of the
233    list) matching the string TOKEN.  If TOKLEN is not 0, the token is
234    assumed to be raw memory of this length.  The function returns a
235    newly allocated S-expression consisting of the found sublist or
236    `NULL' when not found.  */
237 gcry_sexp_t gcry_sexp_find_token (gcry_sexp_t list,
238                                 const char *tok, size_t toklen);
239 /* Return the length of the LIST.  For a valid S-expression this
240    should be at least 1.  */
241 int gcry_sexp_length (const gcry_sexp_t list);
242
243 /* Create and return a new S-expression from the element with index
244    NUMBER in LIST.  Note that the first element has the index 0.  If
245    there is no such element, `NULL' is returned.  */
246 gcry_sexp_t gcry_sexp_nth (const gcry_sexp_t list, int number);
247
248 /* Create and return a new S-expression from the first element in
249    LIST; this called the "type" and should always exist and be a
250    string. `NULL' is returned in case of a problem.  */
251 gcry_sexp_t gcry_sexp_car (const gcry_sexp_t list);
252
253 /* Create and return a new list form all elements except for the first
254    one.  Note, that this function may return an invalid S-expression
255    because it is not guaranteed, that the type exists and is a string.
256    However, for parsing a complex S-expression it might be useful for
257    intermediate lists.  Returns `NULL' on error.  */
258 gcry_sexp_t gcry_sexp_cdr (const gcry_sexp_t list);
259
260 gcry_sexp_t gcry_sexp_cadr (const gcry_sexp_t list);
261
262
263 /* This function is used to get data from a LIST.  A pointer to the
264    actual data with index NUMBER is returned and the length of this
265    data will be stored to DATALEN.  If there is no data at the given
266    index or the index represents another list, `NULL' is returned.
267    *Note:* The returned pointer is valid as long as LIST is not
268    modified or released.  */
269 const char *gcry_sexp_nth_data (const gcry_sexp_t list, int number,
270                                 size_t *datalen);
271
272 /* This function is used to get and convert data from a LIST. This
273    data is assumed to be an MPI stored in the format described by
274    MPIFMT and returned as a standard Libgcrypt MPI.  The caller must
275    release this returned value using `gcry_mpi_release'.  If there is
276    no data at the given index, the index represents a list or the
277    value can't be converted to an MPI, `NULL' is returned.  */
278 gcry_mpi_t gcry_sexp_nth_mpi (gcry_sexp_t list, int number, int mpifmt);
279
280
281 \f
282 /*******************************************
283  *                                         *
284  *  multi precision integer functions      *
285  *                                         *
286  *******************************************/
287
288 /* Different formats of external big integer representation. */
289 enum gcry_mpi_format 
290   {
291     GCRYMPI_FMT_NONE= 0,
292     GCRYMPI_FMT_STD = 1,    /* twos complement stored without length */
293     GCRYMPI_FMT_PGP = 2,    /* As used by OpenPGP (only defined as unsigned)*/
294     GCRYMPI_FMT_SSH = 3,    /* As used by SSH (same as 1 but with length)*/
295     GCRYMPI_FMT_HEX = 4,    /* hex format */
296     GCRYMPI_FMT_USG = 5     /* like STD but this is an unsigned one */
297   };
298
299 /* Flags used for creating big integers.  */
300 enum gcry_mpi_flag 
301   {
302     GCRYMPI_FLAG_SECURE = 1,  /* Allocate the number in "secure" memory. */
303     GCRYMPI_FLAG_OPAQUE = 2   /* The number is not a real one but just a
304                                way to store some bytes.  This is
305                                useful for encrypted big integers. */
306   };
307
308
309 /* Allocate a new big integer object, initialize it with 0 and
310    initially allocate memory for a number of at least NBITS. */
311 gcry_mpi_t gcry_mpi_new (unsigned int nbits);
312
313 /* Same as gcry_mpi_new() but allocate in "secure" memory. */
314 gcry_mpi_t gcry_mpi_snew (unsigned int nbits);
315
316 /* Release the number A and free all associated resources. */
317 void gcry_mpi_release (gcry_mpi_t a);
318
319 /* Create a new number with the same value as A. */
320 gcry_mpi_t gcry_mpi_copy (const gcry_mpi_t a);
321
322 /* Store the big integer value U in W. */
323 gcry_mpi_t gcry_mpi_set (gcry_mpi_t w, const gcry_mpi_t u);
324
325 /* Store the unsigned integer value U in W. */
326 gcry_mpi_t gcry_mpi_set_ui (gcry_mpi_t w, unsigned long u);
327
328 /* Swap the values of A and B. */
329 void gcry_mpi_swap (gcry_mpi_t a, gcry_mpi_t b);
330
331 /* Compare the big integer number U and V returning 0 for equality, a
332    positive value for U > V and a negative for U < V. */
333 int gcry_mpi_cmp (const gcry_mpi_t u, const gcry_mpi_t v);
334
335 /* Compare the big integer number U with the unsigned integer V
336    returning 0 for equality, a positive value for U > V and a negative
337    for U < V. */
338 int gcry_mpi_cmp_ui (const gcry_mpi_t u, unsigned long v);
339
340 /* Convert the external representation of an integer stored in BUFFER
341    with a size of (*NBYTES) in a newly create MPI returned in RET_MPI.
342    For certain formats a length is not required and may be passed as
343    NULL.  After a successful operation NBYTES received the number of
344    bytes actually scanned. */
345 gpg_error_t gcry_mpi_scan (gcry_mpi_t *ret_mpi, enum gcry_mpi_format format,
346                    const char *buffer, size_t *nbytes);
347
348 /* Convert the big integer A into the external representation
349    described by FORMAT and store it in the provided BUFFER which has
350    the size (*NBYTES).  NBYTES receives the actual length of the
351    external representation. */
352 gpg_error_t gcry_mpi_print (enum gcry_mpi_format format,
353                             char *buffer, size_t *nbytes, const gcry_mpi_t a);
354
355 /* Convert the big integer A int the external representation desribed
356    by FORMAT and store it in a newly allocated buffer which address
357    will be put into BUFFER.  NBYTES receives the actual lengths of the
358    external representation. */
359 gpg_error_t gcry_mpi_aprint (enum gcry_mpi_format format,
360                              void **buffer, size_t *nbytes, const gcry_mpi_t a);
361
362 /* W = U + V.  */
363 void gcry_mpi_add (gcry_mpi_t w, gcry_mpi_t u, gcry_mpi_t v);
364
365 /* W = U + V.  V is an unsigned integer. */
366 void gcry_mpi_add_ui (gcry_mpi_t w, gcry_mpi_t u, unsigned long v);
367
368 /* W = U + V mod M. */
369 void gcry_mpi_addm (gcry_mpi_t w, gcry_mpi_t u, gcry_mpi_t v, gcry_mpi_t m);
370
371 /* W = U - V. */
372 void gcry_mpi_sub (gcry_mpi_t w, gcry_mpi_t u, gcry_mpi_t v);
373
374 /* W = U - V.  V is an unsigned integer. */
375 void gcry_mpi_sub_ui (gcry_mpi_t w, gcry_mpi_t u, unsigned long v );
376
377 /* W = U - V mod M */
378 void gcry_mpi_subm (gcry_mpi_t w, gcry_mpi_t u, gcry_mpi_t v, gcry_mpi_t m);
379
380 /* W = U * V. */
381 void gcry_mpi_mul (gcry_mpi_t w, gcry_mpi_t u, gcry_mpi_t v);
382
383 /* W = U * V.  V is an unsigned integer. */
384 void gcry_mpi_mul_ui (gcry_mpi_t w, gcry_mpi_t u, unsigned long v );
385
386 /* W = U * V mod M. */
387 void gcry_mpi_mulm (gcry_mpi_t w, gcry_mpi_t u, gcry_mpi_t v, gcry_mpi_t m);
388
389 /* W = U * (2 ^ CNT). */
390 void gcry_mpi_mul_2exp (gcry_mpi_t w, gcry_mpi_t u, unsigned long cnt);
391
392 /* Q = DIVIDEND / DIVISOR, R = DIVIDEND % DIVISOR,
393    Q or R may be passed as NULL.  ROUND should be negative or 0. */
394 void gcry_mpi_div (gcry_mpi_t q, gcry_mpi_t r,
395                    gcry_mpi_t dividend, gcry_mpi_t divisor, int round);
396
397 /* R = DIVIDEND % DIVISOR */
398 void gcry_mpi_mod (gcry_mpi_t r, gcry_mpi_t dividend, gcry_mpi_t divisor);
399
400 /* W = B ^ E mod M. */
401 void gcry_mpi_powm (gcry_mpi_t w,
402                     const gcry_mpi_t b, const gcry_mpi_t e, const gcry_mpi_t m);
403
404 /* Set G to the greatest common divisor of A and B.  
405    Return true if the G is 1. */
406 int gcry_mpi_gcd (gcry_mpi_t g, gcry_mpi_t a, gcry_mpi_t b);
407
408 /* Set X to the multiplicative inverse of A mod M.
409    Return true if the value exists. */
410 int gcry_mpi_invm (gcry_mpi_t x, gcry_mpi_t a, gcry_mpi_t m);
411
412
413 /* Return the number of bits required to represent A. */
414 unsigned int gcry_mpi_get_nbits (gcry_mpi_t a);
415
416 /* Return true when bit number N (counting from 0) is set in A. */
417 int      gcry_mpi_test_bit (gcry_mpi_t a, unsigned int n);
418
419 /* Set bit number N in A. */
420 void     gcry_mpi_set_bit (gcry_mpi_t a, unsigned int n);
421
422 /* Clear bit number N in A. */
423 void     gcry_mpi_clear_bit (gcry_mpi_t a, unsigned int n);
424
425 /* Set bit number N in A and clear all bits greater than N. */
426 void     gcry_mpi_set_highbit (gcry_mpi_t a, unsigned int n);
427
428 /* Clear bit number N in A and all bits greater than N. */
429 void     gcry_mpi_clear_highbit (gcry_mpi_t a, unsigned int n);
430
431 /* Shift the value of A by N bits to the right and store the result in X. */
432 void     gcry_mpi_rshift (gcry_mpi_t x, gcry_mpi_t a, unsigned int n);
433
434 /* Store NBITS of the value P points to in A and mark A as an opaque
435    value. */
436 gcry_mpi_t gcry_mpi_set_opaque (gcry_mpi_t a, void *p, unsigned int nbits);
437
438 /* Return a pointer to an opaque value stored in A and return its size
439    in NBITS.  Note that the returned pointer is still owned by A and
440    that the function should never be used for an non-opaque MPI. */
441 void *gcry_mpi_get_opaque (gcry_mpi_t a, unsigned int *nbits);
442
443 /* Set the FLAG for the big integer A.  Currently only the flag
444    GCRYMPI_FLAG_SECURE is allowed to convert A into an big intger
445    stored in "secure" memory. */
446 void gcry_mpi_set_flag (gcry_mpi_t a, enum gcry_mpi_flag flag);
447
448 /* Clear FLAG for the big integer A.  Note that this function is
449    currently useless as no flags are allowed. */
450 void gcry_mpi_clear_flag (gcry_mpi_t a, enum gcry_mpi_flag flag);
451
452 /* Return true when the FLAG is set for A. */
453 int gcry_mpi_get_flag (gcry_mpi_t a, enum gcry_mpi_flag flag);
454
455 /* Unless the GCRYPT_NO_MPI_MACROS is used, provide a couple of
456    convenience macors for the big integer functions. */
457 #ifndef GCRYPT_NO_MPI_MACROS
458 #define mpi_new(n)          gcry_mpi_new( (n) )
459 #define mpi_secure_new( n ) gcry_mpi_snew( (n) )
460 #define mpi_release(a)      \
461   do \
462     { \
463       gcry_mpi_release ((a)); \
464       (a) = NULL; \
465     } \
466   while (0)
467
468 #define mpi_copy( a )       gcry_mpi_copy( (a) )
469 #define mpi_set( w, u)      gcry_mpi_set( (w), (u) )
470 #define mpi_set_ui( w, u)   gcry_mpi_set_ui( (w), (u) )
471 #define mpi_cmp( u, v )     gcry_mpi_cmp( (u), (v) )
472 #define mpi_cmp_ui( u, v )  gcry_mpi_cmp_ui( (u), (v) )
473
474 #define mpi_add_ui(w,u,v)   gcry_mpi_add_ui((w),(u),(v))
475 #define mpi_add(w,u,v)      gcry_mpi_add ((w),(u),(v))
476 #define mpi_addm(w,u,v,m)   gcry_mpi_addm ((w),(u),(v),(m))
477 #define mpi_sub_ui(w,u,v)   gcry_mpi_sub_ui ((w),(u),(v))
478 #define mpi_sub(w,u,v)      gcry_mpi_sub ((w),(u),(v))
479 #define mpi_subm(w,u,v,m)   gcry_mpi_subm ((w),(u),(v),(m))
480 #define mpi_mul_ui(w,u,v)   gcry_mpi_mul_ui ((w),(u),(v))
481 #define mpi_mul_2exp(w,u,v) gcry_mpi_mul_2exp ((w),(u),(v))
482 #define mpi_mul(w,u,v)      gcry_mpi_mul ((w),(u),(v))
483 #define mpi_mulm(w,u,v,m)   gcry_mpi_mulm ((w),(u),(v),(m))
484 #define mpi_powm(w,b,e,m)   gcry_mpi_powm ( (w), (b), (e), (m) )
485 #define mpi_tdiv(q,r,a,m)   gcry_mpi_div ( (q), (r), (a), (m), 0)
486 #define mpi_fdiv(q,r,a,m)   gcry_mpi_div ( (q), (r), (a), (m), -1)
487 #define mpi_mod(r,a,m)      gcry_mpi_mod ((r), (a), (m))
488 #define mpi_gcd(g,a,b)      gcry_mpi_gcd ( (g), (a), (b) )
489 #define mpi_invm(g,a,b)     gcry_mpi_invm ( (g), (a), (b) )
490
491 #define mpi_get_nbits(a)       gcry_mpi_get_nbits ((a))
492 #define mpi_test_bit(a,b)      gcry_mpi_test_bit ((a),(b))
493 #define mpi_set_bit(a,b)       gcry_mpi_set_bit ((a),(b))
494 #define mpi_set_highbit(a,b)   gcry_mpi_set_highbit ((a),(b))
495 #define mpi_clear_bit(a,b)     gcry_mpi_clear_bit ((a),(b))
496 #define mpi_clear_highbit(a,b) gcry_mpi_clear_highbit ((a),(b))
497 #define mpi_rshift(a,b,c)      gcry_mpi_rshift ((a),(b),(c))
498
499 #define mpi_set_opaque(a,b,c) gcry_mpi_set_opaque( (a), (b), (c) )
500 #define mpi_get_opaque(a,b)   gcry_mpi_get_opaque( (a), (b) )
501 #endif /* GCRYPT_NO_MPI_MACROS */
502
503
504 \f
505 /************************************
506  *                                  *
507  *   symmetric cipher functions     *
508  *                                  *
509  ************************************/
510
511 /* The data object used to hold a handle to an encryption object.  */
512 struct gcry_cipher_handle;
513 typedef struct gcry_cipher_handle *gcry_cipher_hd_t;
514
515 typedef struct gcry_cipher_handle *GCRY_CIPHER_HD _GCRY_GCC_ATTR_DEPRECATED;
516 typedef struct gcry_cipher_handle *GcryCipherHd _GCRY_GCC_ATTR_DEPRECATED;
517
518 /* All symmetric encryption algorithms are identified by their IDs.
519    More IDs may be registered at runtime. */
520 enum gcry_cipher_algos
521   {
522     GCRY_CIPHER_NONE        = 0,
523     GCRY_CIPHER_IDEA        = 1,
524     GCRY_CIPHER_3DES        = 2,
525     GCRY_CIPHER_CAST5       = 3,
526     GCRY_CIPHER_BLOWFISH    = 4,
527     GCRY_CIPHER_SAFER_SK128 = 5,
528     GCRY_CIPHER_DES_SK      = 6,
529     GCRY_CIPHER_AES         = 7,
530     GCRY_CIPHER_AES192      = 8,
531     GCRY_CIPHER_AES256      = 9,
532     GCRY_CIPHER_TWOFISH     = 10,
533
534     /* other cipher numbers are above 300 for OpenPGP reasons. */
535     GCRY_CIPHER_ARCFOUR     = 301,  /* fully compatible with RSA's RC4 (tm). */
536     GCRY_CIPHER_DES         = 302,  /* Yes, this is single key 56 bit DES. */
537     GCRY_CIPHER_SERPENT128  = 303,
538     GCRY_CIPHER_SERPENT192  = 304,
539     GCRY_CIPHER_SERPENT256  = 305,
540   };
541
542 /* The Rijndael algorithm is basically AES, so provide some macros. */
543 #define GCRY_CIPHER_AES128      GCRY_CIPHER_AES    
544 #define GCRY_CIPHER_RIJNDAEL    GCRY_CIPHER_AES    
545 #define GCRY_CIPHER_RIJNDAEL128 GCRY_CIPHER_AES128 
546 #define GCRY_CIPHER_RIJNDAEL192 GCRY_CIPHER_AES192 
547 #define GCRY_CIPHER_RIJNDAEL256 GCRY_CIPHER_AES256 
548
549 /* The supported encryption modes.  Note that not all of them are
550    supported for each algorithm. */
551 enum gcry_cipher_modes 
552   {
553     GCRY_CIPHER_MODE_NONE   = 0,  /* Not yet specified. */
554     GCRY_CIPHER_MODE_ECB    = 1,  /* Electronic codebook. */
555     GCRY_CIPHER_MODE_CFB    = 2,  /* Cipher feedback. */
556     GCRY_CIPHER_MODE_CBC    = 3,  /* Cipher block chaining. */
557     GCRY_CIPHER_MODE_STREAM = 4,  /* Used with stream ciphers. */
558     GCRY_CIPHER_MODE_OFB    = 5,  /* Outer feedback. */
559     GCRY_CIPHER_MODE_CTR    = 6   /* Counter. */
560   };
561
562 /* Flags used with the open function. */ 
563 enum gcry_cipher_flags
564   {
565     GCRY_CIPHER_SECURE      = 1,  /* Allocate in secure memory. */
566     GCRY_CIPHER_ENABLE_SYNC = 2,  /* Enable CFB sync mode. */
567     GCRY_CIPHER_CBC_CTS     = 4,  /* Enable CBC cipher text stealing (CTS). */
568     GCRY_CIPHER_CBC_MAC     = 8   /* Enable CBC message auth. code (MAC). */
569   };
570
571
572 /* Create a handle for algorithm ALGO to be used in MODE.  FLAGS may
573    be given as an bitwise OR of the gcry_cipher_flags values. */
574 gpg_error_t gcry_cipher_open (gcry_cipher_hd_t *handle,
575                               int algo, int mode, unsigned int flags);
576
577 /* Close the cioher handle H and release all resource. */
578 void gcry_cipher_close (gcry_cipher_hd_t h);
579
580 /* Perform various operations on the cipher object H. */
581 gpg_error_t gcry_cipher_ctl (gcry_cipher_hd_t h, int cmd, void *buffer,
582                              size_t buflen);
583
584 /* Retrieve various information about the cipher object H. */
585 gpg_error_t gcry_cipher_info (gcry_cipher_hd_t h, int what, void *buffer,
586                               size_t *nbytes);
587
588 /* Retrieve various information about the cipher algorithm ALGO. */
589 gpg_error_t gcry_cipher_algo_info (int algo, int what, void *buffer,
590                                    size_t *nbytes);
591
592 /* Map the cipher algorithm id ALGO to a string representation of that
593    algorithm name.  For unknown algorithms this functions returns an
594    empty string. */
595 const char *gcry_cipher_algo_name (int algo) _GCRY_GCC_ATTR_PURE;
596
597 /* Map the algorithm name NAME to an cipher algorithm ID.  Return 0 if
598    the algorithm name is not known. */
599 int gcry_cipher_map_name (const char *name) _GCRY_GCC_ATTR_PURE;
600
601 /* Given an ASN.1 object identifier in standard IETF dotted decimal
602    format in STING, return the encryption mode associated with that
603    OID or 0 if not known or applicable. */
604 int gcry_cipher_mode_from_oid (const char *string) _GCRY_GCC_ATTR_PURE;
605
606 /* Encrypt the plaintext of size INLEN in IN using the cipher handle H
607    into the buffer OUT which has an allocated length of OUTSIZE.  For
608    most algorithms it is possible to pass NULL for in and 0 for INLEN
609    and do a in-place decryption of the data provided in OUT.  */
610 gpg_error_t gcry_cipher_encrypt (gcry_cipher_hd_t h,
611                                  unsigned char *out, size_t outsize,
612                                  const unsigned char *in, size_t inlen);
613
614 /* The counterpart to gcry_cipher_encrypt.  */
615 gpg_error_t gcry_cipher_decrypt (gcry_cipher_hd_t h,
616                                  unsigned char *out, size_t outsize,
617                                  const unsigned char *in, size_t inlen);
618
619 /* Set key K of length L for the cipher handle H.  (We have to cast
620    away a const char* here - this catch-all ctl function was probably
621    not the best choice) */
622 #define gcry_cipher_setkey(h,k,l)  gcry_cipher_ctl( (h), GCRYCTL_SET_KEY, \
623                                                          (char*)(k), (l) )
624
625 /* Set initialization vector K of length L for the cipher handle H. */
626 #define gcry_cipher_setiv(h,k,l)  gcry_cipher_ctl( (h), GCRYCTL_SET_IV, \
627                                                          (char*)(k), (l) )
628
629 /* Reset the handle to the state after open.  */
630 #define gcry_cipher_reset(h)  gcry_cipher_ctl ((h), GCRYCTL_RESET, NULL, 0)
631
632 /* Perform the the OpenPGP sync operation if this is enabled for the
633    cipher handle H. */
634 #define gcry_cipher_sync(h)  gcry_cipher_ctl( (h), GCRYCTL_CFB_SYNC, \
635                                                                    NULL, 0 )
636
637 /* Enable or disable CTS in future calls to gcry_encrypt(). CBC mode only. */
638 #define gcry_cipher_cts(h,on)  gcry_cipher_ctl( (h), GCRYCTL_SET_CBC_CTS, \
639                                                                    NULL, on )
640
641 /* Set counter for CTR mode.  (K,L) must denote a buffer of block size
642    length, or (NULL,0) to set the CTR to the all-zero block. */
643 #define gcry_cipher_setctr(h,k,l)  gcry_cipher_ctl( (h), GCRYCTL_SET_CTR, \
644                                                     (char*)(k), (l) )
645
646 /* Retrieved the key length used with algorithm A. */
647 size_t gcry_cipher_get_algo_keylen (int algo);
648
649 /* Retrieve the block length used with algorithm A. */
650 size_t gcry_cipher_get_algo_blklen (int algo);
651
652 /* Return 0 if the algorithm A is available for use. */
653 #define gcry_cipher_test_algo(a) \
654             gcry_cipher_algo_info( (a), GCRYCTL_TEST_ALGO, NULL, NULL )
655
656 /* Get a list consisting of the IDs of the loaded cipher modules.  If
657    LIST is zero, write the number of loaded cipher modules to
658    LIST_LENGTH and return.  If LIST is non-zero, the first
659    *LIST_LENGTH algorithm IDs are stored in LIST, which must be of
660    according size.  In case there are less cipher modules than
661    *LIST_LENGTH, *LIST_LENGTH is updated to the correct number.  */
662 gpg_error_t gcry_cipher_list (int *list, int *list_length);
663
664 /* Type for the cipher_setkey function.  */
665 typedef gpg_err_code_t (*gcry_cipher_setkey_t) (void *c,
666                                                 const unsigned char *key,
667                                                 unsigned keylen);
668
669 /* Type for the cipher_encrypt function.  */
670 typedef void (*gcry_cipher_encrypt_t) (void *c,
671                                        unsigned char *outbuf,
672                                        const unsigned char *inbuf);
673
674 /* Type for the cipher_decrypt function.  */
675 typedef void (*gcry_cipher_decrypt_t) (void *c,
676                                        unsigned char *outbuf,
677                                        const unsigned char *inbuf);
678
679 /* Type for the cipher_stencrypt function.  */
680 typedef void (*gcry_cipher_stencrypt_t) (void *c,
681                                          unsigned char *outbuf,
682                                          const unsigned char *inbuf,
683                                          unsigned int n);
684
685 /* Type for the cipher_stdecrypt function.  */
686 typedef void (*gcry_cipher_stdecrypt_t) (void *c,
687                                          unsigned char *outbuf,
688                                          const unsigned char *inbuf,
689                                          unsigned int n);
690
691 /* Module specification structure for ciphers.  */
692 typedef struct gcry_cipher_spec
693 {
694   const char *name;
695   size_t blocksize;
696   size_t keylen;
697   size_t contextsize;
698   gcry_cipher_setkey_t setkey;
699   gcry_cipher_encrypt_t encrypt;
700   gcry_cipher_decrypt_t decrypt;
701   gcry_cipher_stencrypt_t stencrypt;
702   gcry_cipher_stdecrypt_t stdecrypt;
703 } gcry_cipher_spec_t;
704
705 /* Register a new cipher module whose specification can be found in
706    CIPHER.  On success, a new algorithm ID is stored in ALGORITHM_ID
707    and a pointer representhing this module is stored in MODULE.  */
708 gpg_error_t gcry_cipher_register (gcry_cipher_spec_t *cipher,
709                                   unsigned int *algorithm_id,
710                                   gcry_module_t *module);
711
712 /* Unregister the cipher identified by MODULE, which must have been
713    registered with gcry_cipher_register.  */
714 void gcry_cipher_unregister (gcry_module_t module);
715
716 \f
717 /************************************
718  *                                  *
719  *    asymmetric cipher functions   *
720  *                                  *
721  ************************************/
722
723 /* The algorithms and their IDs we support. */
724 enum gcry_pk_algos 
725   {
726     GCRY_PK_RSA = 1,
727     GCRY_PK_RSA_E = 2,      /* deprecated */
728     GCRY_PK_RSA_S = 3,      /* deprecated */
729     GCRY_PK_ELG_E = 16,     /* use only for OpenPGP */
730     GCRY_PK_DSA   = 17,
731     GCRY_PK_ELG   = 20
732   };
733
734 /* Flags describing usage capabilities of a PK algorithm. */
735 #define GCRY_PK_USAGE_SIGN 1
736 #define GCRY_PK_USAGE_ENCR 2
737
738 /* Encrypt the DATA using the public key PKEY and store the result as
739    a newly created S-expression at RESULT. */
740 gpg_error_t gcry_pk_encrypt (gcry_sexp_t *result, gcry_sexp_t data, gcry_sexp_t pkey);
741
742 /* Decrypt the DATA using the private key SKEY and store the result as
743    a newly created S-expression at RESULT. */
744 gpg_error_t gcry_pk_decrypt (gcry_sexp_t *result, gcry_sexp_t data, gcry_sexp_t skey);
745
746 /* Sign the DATA using the private key SKEY and store the result as
747    a newly created S-expression at RESULT. */
748 gpg_error_t gcry_pk_sign (gcry_sexp_t *result, gcry_sexp_t data, gcry_sexp_t skey);
749
750 /* Check the signature SIGVAL on DATA using the public key PKEY. */
751 gpg_error_t gcry_pk_verify (gcry_sexp_t sigval, gcry_sexp_t data, gcry_sexp_t pkey);
752
753 /* Check that KEY (either private or public) is sane. */
754 gpg_error_t gcry_pk_testkey (gcry_sexp_t key);
755
756 /* Generate a new key pair according to the parameters given in
757    S_PARMS.  The new key pair is returned in as an S-expression in
758    R_KEY. */
759 gpg_error_t gcry_pk_genkey (gcry_sexp_t *r_key, gcry_sexp_t s_parms);
760
761 /* Catch all function for miscellaneous operations. */
762 gpg_error_t gcry_pk_ctl (int cmd, void *buffer, size_t buflen);
763
764 /* Retrieve information about the public key algorithm ALGO. */
765 gpg_error_t gcry_pk_algo_info (int algo, int what, void *buffer, size_t *nbytes);
766
767 /* Map the public key algorithm id ALGO to a string representation of the
768    algorithm name.  For unknown algorithms this functions returns an
769    empty string. */
770 const char *gcry_pk_algo_name (int algo) _GCRY_GCC_ATTR_PURE;
771
772 /* Map the algorithm NAME to a public key algorithm Id.  Return 0 if
773    the algorithm name is not known. */
774 int gcry_pk_map_name (const char* name) _GCRY_GCC_ATTR_PURE;
775
776 /* Return what is commonly referred as the key length for the given
777    public or private KEY.  */
778 unsigned int gcry_pk_get_nbits (gcry_sexp_t key) _GCRY_GCC_ATTR_PURE;
779
780 /* Please note that keygrip is still experimental and should not be
781    used without contacting the author. */
782 unsigned char *gcry_pk_get_keygrip (gcry_sexp_t key, unsigned char *array);
783
784 /* Return 0 if the public key algorithm A is available for use. */
785 #define gcry_pk_test_algo(a) \
786             gcry_pk_algo_info( (a), GCRYCTL_TEST_ALGO, NULL, NULL )
787
788 /* Get a list consisting of the IDs of the loaded pubkey modules.  If
789    LIST is zero, write the number of loaded pubkey modules to
790    LIST_LENGTH and return.  If LIST is non-zero, the first
791    *LIST_LENGTH algorithm IDs are stored in LIST, which must be of
792    according size.  In case there are less pubkey modules than
793    *LIST_LENGTH, *LIST_LENGTH is updated to the correct number.  */
794 gpg_error_t gcry_pk_list (int *list, int *list_length);
795
796 /* Type for the pk_generate function.  */
797 typedef gpg_err_code_t (*gcry_pk_generate_t) (int algo,
798                                               unsigned int nbits,
799                                               unsigned long use_e,
800                                               gcry_mpi_t *skey,
801                                               gcry_mpi_t **retfactors);
802
803 /* Type for the pk_check_secret_key function.  */
804 typedef gpg_err_code_t (*gcry_pk_check_secret_key_t) (int algo,
805                                                       gcry_mpi_t *skey);
806
807 /* Type for the pk_encrypt function.  */
808 typedef gpg_err_code_t (*gcry_pk_encrypt_t) (int algo,
809                                              gcry_mpi_t *resarr,
810                                              gcry_mpi_t data,
811                                              gcry_mpi_t *pkey,
812                                              int flags);
813
814 /* Type for the pk_decrypt function.  */
815 typedef gpg_err_code_t (*gcry_pk_decrypt_t) (int algo,
816                                              gcry_mpi_t *result,
817                                              gcry_mpi_t *data,
818                                              gcry_mpi_t *skey,
819                                              int flags);
820
821 /* Type for the pk_sign function.  */
822 typedef gpg_err_code_t (*gcry_pk_sign_t) (int algo,
823                                           gcry_mpi_t *resarr,
824                                           gcry_mpi_t data,
825                                           gcry_mpi_t *skey);
826
827 /* Type for the pk_verify function.  */
828 typedef gpg_err_code_t (*gcry_pk_verify_t) (int algo,
829                                             gcry_mpi_t hash,
830                                             gcry_mpi_t *data,
831                                             gcry_mpi_t *pkey,
832                                             int (*cmp) (void *, gcry_mpi_t),
833                                             void *opaquev);
834
835 /* Type for the pk_get_nbits function.  */
836 typedef unsigned (*gcry_pk_get_nbits_t) (int algo, gcry_mpi_t *pkey);
837
838 /* Module specification structure for message digests.  */
839 typedef struct gcry_pk_spec
840 {
841   const char *name;
842   char **sexp_names;
843   const char *elements_pkey;
844   const char *elements_skey;
845   const char *elements_enc;
846   const char *elements_sig;
847   const char *elements_grip;
848   int use;
849   gcry_pk_generate_t generate;
850   gcry_pk_check_secret_key_t check_secret_key;
851   gcry_pk_encrypt_t encrypt;
852   gcry_pk_decrypt_t decrypt;
853   gcry_pk_sign_t sign;
854   gcry_pk_verify_t verify;
855   gcry_pk_get_nbits_t get_nbits;
856 } gcry_pk_spec_t;
857
858 /* Register a new pubkey module whose specification can be found in
859    PUBKEY.  On success, a new algorithm ID is stored in ALGORITHM_ID
860    and a pointer representhing this module is stored in MODULE.  */
861 gpg_error_t gcry_pk_register (gcry_pk_spec_t *pubkey,
862                               unsigned int *algorithm_id,
863                               gcry_module_t *module);
864
865 /* Unregister the pubkey identified by ID, which must have been
866    registered with gcry_pk_register.  */
867 void gcry_pk_unregister (gcry_module_t module);
868
869 /* Alternative interface for asymetric cryptography.  */
870
871 /* The algorithm IDs. */
872 typedef enum gcry_ac_id
873   {
874     GCRY_AC_RSA = 1,
875     GCRY_AC_DSA = 17,
876     GCRY_AC_ELG = 20,
877   }
878 gcry_ac_id_t;
879
880 /* Key types.  */
881 typedef enum gcry_ac_key_type
882   {
883     GCRY_AC_KEY_SECRET,
884     GCRY_AC_KEY_PUBLIC,
885   }
886 gcry_ac_key_type_t;
887
888 /* Flags for data. */
889 #define GCRY_AC_FLAG_DATA_NO_BLINDING 1 << 0
890
891 /* This type represents a `data set'.  */
892 typedef struct gcry_ac_data *gcry_ac_data_t;
893
894 /* This type represents a single `key', either a secret one or a
895    public one.  */
896 typedef struct gcry_ac_key *gcry_ac_key_t;
897
898 /* This type represents a `key pair' containing a secret and a public
899    key.  */
900 typedef struct gcry_ac_key_pair *gcry_ac_key_pair_t;
901
902 /* This type represents a `handle' that is needed by functions
903    performing cryptographic operations.  */
904 typedef struct gcry_ac_handle *gcry_ac_handle_t;
905
906 /* The caller of gcry_ac_key_pair_generate can provide one of these
907    structures in order to influence the key generation process in an
908    algorithm-specific way.  */
909 typedef struct gcry_ac_key_spec_rsa
910 {
911   gcry_mpi_t e;                 /* E to use.  */
912 } gcry_ac_key_spec_rsa_t;
913
914 /* Returns a new, empty data set in DATA.  */
915 gpg_error_t gcry_ac_data_new (gcry_ac_data_t *data);
916
917 /* Destroy the data set DATA.  */
918 void gcry_ac_data_destroy (gcry_ac_data_t data);
919
920 /* Add the value MPI to DATA with the label NAME.  If there is already
921    a value with that label, replace it, otherwise add it.  */
922 gpg_error_t gcry_ac_data_set (gcry_ac_data_t data,
923                               const char *name,
924                               gcry_mpi_t mpi);
925
926 /* Return the number of named MPI values inside of the data set
927    DATA.  */
928 unsigned int gcry_ac_data_length (gcry_ac_data_t data);
929
930 /* Store the value labelled with NAME found in DATA in MPI or NULL if
931    a value with that label was not found.  */
932 gpg_error_t gcry_ac_data_get_name (gcry_ac_data_t data, const char *name,
933                                    gcry_mpi_t *mpi);
934
935 /* Return the MPI value with index INDEX contained in the data set
936    DATA.  */
937 gpg_error_t gcry_ac_data_get_index (gcry_ac_data_t data, unsigned int index,
938                                     const char **name, gcry_mpi_t *mpi);
939
940 /* Destroy any values contained in the data set DATA.  */
941 void gcry_ac_data_clear (gcry_ac_data_t data);
942
943 /* Create a new ac handle.  */
944 gpg_error_t gcry_ac_open (gcry_ac_handle_t *handle,
945                           gcry_ac_id_t algorithm,
946                           unsigned int flags);
947
948 /* Destroy an ac handle.  */
949 void gcry_ac_close (gcry_ac_handle_t handle);
950
951 /* Initialize a key from a given data set.  */
952 gpg_error_t gcry_ac_key_init (gcry_ac_key_t *key,
953                               gcry_ac_handle_t handle,
954                               gcry_ac_key_type_t type,
955                               gcry_ac_data_t data);
956
957 /* Generate a new key pair.  */
958 gpg_error_t gcry_ac_key_pair_generate (gcry_ac_handle_t handle,
959                                        gcry_ac_key_pair_t *key_pair,
960                                        unsigned int nbits,
961                                        void *spec);
962
963 /* Returns a specified key from a key pair.  */
964 gcry_ac_key_t gcry_ac_key_pair_extract (gcry_ac_key_pair_t key_pair,
965                                         gcry_ac_key_type_t which);
966
967 /* Verify that the key KEY is sane.  */
968 gpg_error_t gcry_ac_key_test (gcry_ac_key_t key);
969
970 /* Return the number of bits of the key KEY in NBITS.  */
971 gpg_error_t gcry_ac_key_get_nbits (gcry_ac_key_t key,
972                                    unsigned int *nbits);
973
974 /* Write the 20 byte long key grip of the key KEY to KEY_GRIP.  */
975 gpg_error_t gcry_ac_key_get_grip (gcry_ac_key_t key,
976                                   unsigned char *key_grip);
977
978 /* Destroy a key.  */
979 void gcry_ac_key_destroy (gcry_ac_key_t key);
980
981 /* Destroy a key pair.  */
982 void gcry_ac_key_pair_destroy (gcry_ac_key_pair_t key_pair);
983
984 /* Encrypt the plain text MPI value DATA_PLAIN with the key KEY under
985    the control of the flags FLAGS and store the resulting data set
986    into DATA_ENCRYPTED.  */
987 gpg_error_t gcry_ac_data_encrypt (gcry_ac_handle_t handle,
988                                   unsigned int flags,
989                                   gcry_ac_key_t key,
990                                   gcry_mpi_t data_plain,
991                                   gcry_ac_data_t *data_encrypted);
992
993 /* Decrypt the decrypted data contained in the data set DATA_ENCRYPTED
994    with the key KEY under the control of the flags FLAGS and store the
995    resulting plain text MPI value in DATA_PLAIN.  */
996 gpg_error_t gcry_ac_data_decrypt (gcry_ac_handle_t handle,
997                                   unsigned int flags,
998                                   gcry_ac_key_t key,
999                                   gcry_mpi_t *data_plain,
1000                                   gcry_ac_data_t data_encrypted);
1001
1002 /* Sign the data contained in DATA with the key KEY and store the
1003    resulting signature in the data set DATA_SIGNATURE.  */
1004 gpg_error_t gcry_ac_data_sign (gcry_ac_handle_t handle,
1005                                gcry_ac_key_t key,
1006                                gcry_mpi_t data,
1007                                gcry_ac_data_t *data_signature);
1008
1009 /* Verify that the signature contained in the data set DATA_SIGNATURE
1010    is indeed the result of signing the data contained in DATA with the
1011    secret key belonging to the public key KEY.  */
1012 gpg_error_t gcry_ac_data_verify (gcry_ac_handle_t handle,
1013                                  gcry_ac_key_t key,
1014                                  gcry_mpi_t data,
1015                                  gcry_ac_data_t data_signature);
1016
1017 /* Store the textual representation of the algorithm whose id is given
1018    in ALGORITHM in NAME.  */
1019 gpg_error_t gcry_ac_id_to_name (gcry_ac_id_t algorithm,
1020                                 const char **name);
1021
1022 /* Store the numeric ID of the algorithm whose textual representation
1023    is contained in NAME in ALGORITHM.  */
1024 gpg_error_t gcry_ac_name_to_id (const char *name,
1025                                 gcry_ac_id_t *algorithm);
1026
1027 \f
1028
1029 /************************************
1030  *                                  *
1031  *   cryptograhic hash functions    *
1032  *                                  *
1033  ************************************/
1034
1035 /* Algorithm IDs for the hash functions we know about. Not all of them
1036    are implemnted. */
1037 enum gcry_md_algos
1038   {
1039     GCRY_MD_NONE    = 0,  
1040     GCRY_MD_MD5     = 1,
1041     GCRY_MD_SHA1    = 2,
1042     GCRY_MD_RMD160  = 3,
1043     GCRY_MD_MD2     = 5,
1044     GCRY_MD_TIGER   = 6,   /* TIGER/192. */
1045     GCRY_MD_HAVAL   = 7,   /* HAVAL, 5 pass, 160 bit. */
1046     GCRY_MD_SHA256  = 8,
1047     GCRY_MD_SHA384  = 9,
1048     GCRY_MD_SHA512  = 10,
1049     GCRY_MD_MD4     = 301,
1050     GCRY_MD_CRC32               = 302,
1051     GCRY_MD_CRC32_RFC1510       = 303,
1052     GCRY_MD_CRC24_RFC2440       = 304
1053   };
1054
1055 /* Flags used with the open function. */
1056 enum gcry_md_flags
1057   {
1058     GCRY_MD_FLAG_SECURE = 1,  /* Allocate all buffers in "secure" memory */
1059     GCRY_MD_FLAG_HMAC   = 2   /* Make an HMAC out of this algorithm. */
1060   };
1061
1062
1063 /* This object is used to hold a handle to an message digest object.  */
1064 struct gcry_md_context;
1065 struct gcry_md_handle 
1066   { /* This structure is private - only to be used by the gcry_md_  macros. */
1067     struct gcry_md_context *ctx;
1068     int  bufpos;
1069     int  bufsize;
1070     unsigned char buf[1];
1071   };
1072 typedef struct gcry_md_handle *gcry_md_hd_t;
1073
1074 typedef struct gcry_md_handle *GCRY_MD_HD _GCRY_GCC_ATTR_DEPRECATED;
1075 typedef struct gcry_md_handle *GcryMDHd _GCRY_GCC_ATTR_DEPRECATED;
1076
1077
1078 /* Create a message digest object for algorithm ALGO.  FLAGS may be
1079    given as an bitwise OR of the gcry_md_flags values.  ALGO may be
1080    given as 0 if the algorithms to be used are later set using
1081    gcry_md_enable. */
1082 gpg_error_t gcry_md_open (gcry_md_hd_t *h, int algo, unsigned int flags);
1083
1084 /* Release the message digest object HD. */
1085 void gcry_md_close (gcry_md_hd_t hd);
1086
1087 /* Add the message digest algorithm ALGO to the digest object HD. */
1088 gpg_error_t gcry_md_enable( gcry_md_hd_t hd, int algo );
1089
1090 /* Create a new digest object as an exact copy of the object HD. */
1091 gpg_error_t gcry_md_copy (gcry_md_hd_t *bhd, gcry_md_hd_t ahd);
1092
1093 /* Reset the digest object HD to its initial state. */
1094 void gcry_md_reset (gcry_md_hd_t hd);
1095
1096 /* Perform various operations on the digets object HD. */
1097 gpg_error_t gcry_md_ctl (gcry_md_hd_t hd, int cmd, unsigned char *buffer,
1098                          size_t buflen);
1099
1100 /* Pass LENGTH bytes of data in BUFFER to the digest object HD so that
1101    it can update the digest values.  This is the actual hash
1102    function. */
1103 void gcry_md_write (gcry_md_hd_t hd, const void *buffer, size_t length);
1104
1105 /* Read out the final digest from HD return the digest value for
1106    algorithm ALGO. */
1107 unsigned char *gcry_md_read (gcry_md_hd_t hd, int algo);
1108
1109 /* Convenience function to calculate the hash from the data in BUFFER
1110    of size LENGTH using the algorithm ALGO avoiding the creating of a
1111    hash object.  The hash is returned in the caller provided buffer
1112    DIGEST which must be large enough to hold the digest of the given
1113    algorithm. */
1114 void gcry_md_hash_buffer (int algo, void *digest,
1115                           const void *buffer, size_t length);
1116
1117 /* Retrieve the algorithm used with HD.  This does not work reliable
1118    if more than one algorithm is enabled in HD. */
1119 int gcry_md_get_algo (gcry_md_hd_t hd);
1120
1121 /* Retrieve the length in bytes of the digest yielded by algorithm
1122    ALGO. */
1123 unsigned int gcry_md_get_algo_dlen (int algo);
1124
1125 /* Return true if the the algorithm ALGO is enabled in the digest
1126    object A. */
1127 int gcry_md_is_enabled (gcry_md_hd_t a, int algo);
1128
1129 /* Return true if the digest object A is allocated in "secure" memory. */
1130 int gcry_md_is_secure (gcry_md_hd_t a);
1131
1132 /* Retrieve various information about the object H.  */
1133 gpg_error_t gcry_md_info (gcry_md_hd_t h, int what, void *buffer,
1134                           size_t *nbytes);
1135
1136 /* Retrieve various information about the algorithm ALGO.  */
1137 gpg_error_t gcry_md_algo_info (int algo, int what, void *buffer,
1138                                size_t *nbytes);
1139
1140 /* Map the digest algorithm id ALGO to a string representation of the
1141    algorithm name.  For unknown algorithms this functions returns an
1142    empty string. */
1143 const char *gcry_md_algo_name (int algo) _GCRY_GCC_ATTR_PURE;
1144
1145 /* Map the algorithm NAME to a digest algorithm Id.  Return 0 if
1146    the algorithm name is not known. */
1147 int gcry_md_map_name (const char* name) _GCRY_GCC_ATTR_PURE;
1148
1149 /* For use with the HMAC feature, the set MAC key to the KEY of
1150    KEYLEN. */
1151 gpg_error_t gcry_md_setkey (gcry_md_hd_t hd, const void *key, size_t keylen);
1152
1153 /* Update the hash(s) of H with the character C.  This is a buffered
1154    version of the gcry_md_write function. */
1155 #define gcry_md_putc(h,c)  \
1156             do {                                          \
1157                 gcry_md_hd_t h__ = (h);                       \
1158                 if( (h__)->bufpos == (h__)->bufsize )     \
1159                     gcry_md_write( (h__), NULL, 0 );      \
1160                 (h__)->buf[(h__)->bufpos++] = (c) & 0xff; \
1161             } while(0)
1162
1163 /* Finalize the digest calculation.  This is not really needed because
1164    gcry_md_read() does this implicitly. */
1165 #define gcry_md_final(a) \
1166             gcry_md_ctl ((a), GCRYCTL_FINALIZE, NULL, 0)
1167
1168 /* Return 0 if the algorithm A is available for use. */
1169 #define gcry_md_test_algo(a) \
1170             gcry_md_algo_info( (a), GCRYCTL_TEST_ALGO, NULL, NULL )
1171
1172 /* Return an DER encoded ASN.1 OID for the algorithm A in buffer B. N
1173    must point to size_t variable with the available size of buffer B.
1174    After return it will receive the actual size of the returned
1175    OID. */
1176 #define gcry_md_get_asnoid(a,b,n) \
1177             gcry_md_algo_info((a), GCRYCTL_GET_ASNOID, (b), (n))
1178
1179 /* Enable debugging for digets object A; i.e. create files named
1180    dbgmd-<n>.<string> while hashing.  B is a string used as the suffix
1181    for the filename. */
1182 #define gcry_md_start_debug(a,b) \
1183             gcry_md_ctl( (a), GCRYCTL_START_DUMP, (b), 0 )
1184
1185 /* Disable the debugging of A. */
1186 #define gcry_md_stop_debug(a,b) \
1187             gcry_md_ctl( (a), GCRYCTL_STOP_DUMP, (b), 0 )
1188
1189 /* Get a list consisting of the IDs of the loaded message digest
1190    modules.  If LIST is zero, write the number of loaded message
1191    digest modules to LIST_LENGTH and return.  If LIST is non-zero, the
1192    first *LIST_LENGTH algorithm IDs are stored in LIST, which must be
1193    of according size.  In case there are less message digest modules
1194    than *LIST_LENGTH, *LIST_LENGTH is updated to the correct
1195    number.  */
1196 gpg_error_t gcry_md_list (int *list, int *list_length);
1197
1198 /* Type for the md_init function.  */
1199 typedef void (*gcry_md_init_t) (void *c);
1200
1201 /* Type for the md_write function.  */
1202 typedef void (*gcry_md_write_t) (void *c, unsigned char *buf, size_t nbytes);
1203
1204 /* Type for the md_final function.  */
1205 typedef void (*gcry_md_final_t) (void *c);
1206
1207 /* Type for the md_read function.  */
1208 typedef unsigned char *(*gcry_md_read_t) (void *c);
1209
1210 /* Module specification structure for message digests.  */
1211 typedef struct gcry_md_spec
1212 {
1213   const char *name;
1214   unsigned char *asnoid;
1215   int asnlen;
1216   int mdlen;
1217   gcry_md_init_t init;
1218   gcry_md_write_t write;
1219   gcry_md_final_t final;
1220   gcry_md_read_t read;
1221   size_t contextsize; /* allocate this amount of context */
1222 } gcry_md_spec_t;
1223
1224 /* Register a new digest module whose specification can be found in
1225    DIGEST.  On success, a new algorithm ID is stored in ALGORITHM_ID
1226    and a pointer representhing this module is stored in MODULE.  */
1227 gpg_error_t gcry_md_register (gcry_md_spec_t *digest,
1228                               unsigned int *algorithm_id,
1229                               gcry_module_t *module);
1230
1231 /* Unregister the digest identified by ID, which must have been
1232    registered with gcry_digest_register.  */
1233 void gcry_md_unregister (gcry_module_t module);
1234
1235
1236 \f
1237 /************************************
1238  *                                  *
1239  *   random generating functions    *
1240  *                                  *
1241  ************************************/
1242
1243 /* The possible values for the random quality.  The rule of thumb is
1244    to use WEAK for random number which don't need to be
1245    cryptographically strong, STRONG for session keys and VERY_STRONG
1246    for key material. */
1247 enum gcry_random_level
1248   {
1249     GCRY_WEAK_RANDOM = 0,
1250     GCRY_STRONG_RANDOM = 1,
1251     GCRY_VERY_STRONG_RANDOM = 2
1252   };
1253
1254
1255 /* Fill BUFFER with LENGTH bytes of random, using random numbers of
1256    quality LEVEL. */
1257 void gcry_randomize (unsigned char *buffer, size_t length,
1258                      enum gcry_random_level level);
1259
1260 /* Add the external random from BUFFER with LENGTH bytes into the
1261    pool. QUALITY should either be -1 for unknown or in the range of 0
1262    to 100 */
1263 gpg_error_t gcry_random_add_bytes (const void *buffer, size_t length,
1264                                    int quality);
1265
1266 /* Return NBYTES of allocated random using a random numbers of quality
1267    LEVEL. */
1268 void *gcry_random_bytes (size_t nbytes, enum gcry_random_level level)
1269                          _GCRY_GCC_ATTR_MALLOC;
1270
1271 /* Return NBYTES of allocated random using a random numbers of quality
1272    LEVEL.  The random numbers are created returned in "secure"
1273    memory. */
1274 void *gcry_random_bytes_secure (size_t nbytes, enum gcry_random_level level)
1275                                 _GCRY_GCC_ATTR_MALLOC;
1276
1277
1278 /* Set the big inetger W to a random value of NBITS using a random
1279    generator with quality LEVEL. */
1280 void gcry_mpi_randomize (gcry_mpi_t w,
1281                          unsigned int nbits, enum gcry_random_level level);
1282
1283
1284 \f
1285 /************************************
1286  *                                  *
1287  *     miscellaneous stuff          *
1288  *                                  *
1289  ************************************/
1290
1291 /* Log levels used by the internal logging facility. */
1292 enum gcry_log_levels 
1293   {
1294     GCRY_LOG_CONT   = 0,    /* continue the last log line */
1295     GCRY_LOG_INFO   = 10,
1296     GCRY_LOG_WARN   = 20,
1297     GCRY_LOG_ERROR  = 30,
1298     GCRY_LOG_FATAL  = 40,
1299     GCRY_LOG_BUG    = 50,
1300     GCRY_LOG_DEBUG  = 100
1301   };
1302
1303 /* Type for progress handlers.  */
1304 typedef void (*gcry_handler_progress_t) (void *, const char *, int, int, int);
1305
1306 /* Type for memory allocation handlers.  */
1307 typedef void *(*gcry_handler_alloc_t) (size_t n);
1308
1309 /* Type for secure memory check handlers.  */
1310 typedef int (*gcry_handler_secure_check_t) (const void *);
1311
1312 /* Type for memory reallocation handlers.  */
1313 typedef void *(*gcry_handler_realloc_t) (void *p, size_t n);
1314
1315 /* Type for memory free handlers.  */
1316 typedef void (*gcry_handler_free_t) (void *);
1317
1318 /* Type for out-of-memory handlers.  */
1319 typedef int (*gcry_handler_no_mem_t) (void *, size_t, unsigned int);
1320
1321 /* Type for fatal error handlers.  */
1322 typedef void (*gcry_handler_error_t) (void *, int, const char *);
1323
1324 /* Type for logging handlers.  */
1325 typedef void (*gcry_handler_log_t) (void *, int, const char *, va_list);
1326
1327 /* Certain operations can provide progress information.  This function
1328    is used to register a handler for retrieving these information. */
1329 void gcry_set_progress_handler (gcry_handler_progress_t cb, void *cb_data);
1330
1331
1332 /* Register a custom memory allocation functions. */
1333 void gcry_set_allocation_handler (gcry_handler_alloc_t func_alloc,
1334                                   gcry_handler_alloc_t func_alloc_secure,
1335                                   gcry_handler_secure_check_t func_secure_check,
1336                                   gcry_handler_realloc_t func_realloc,
1337                                   gcry_handler_free_t func_free);
1338
1339 /* Register a function used instead of the internal out of memory
1340    handler. */
1341 void gcry_set_outofcore_handler (gcry_handler_no_mem_t h, void *opaque);
1342
1343 /* Register a function used instead of the internal fatal error
1344    handler. */
1345 void gcry_set_fatalerror_handler (gcry_handler_error_t fnc, void *opaque);
1346
1347 /* Register a function used instead of the internal logging
1348    facility. */
1349 void gcry_set_log_handler (gcry_handler_log_t f, void *opaque);
1350
1351 /* Reserved for future use. */
1352 void gcry_set_gettext_handler (const char *(*f)(const char*));
1353
1354 /* Libgcrypt uses its own memory allocation.  It is important to use
1355    gcry_free () to release memory allocated by libgcrypt. */
1356 void *gcry_malloc (size_t n) _GCRY_GCC_ATTR_MALLOC;
1357 void *gcry_calloc (size_t n, size_t m) _GCRY_GCC_ATTR_MALLOC;
1358 void *gcry_malloc_secure (size_t n) _GCRY_GCC_ATTR_MALLOC;
1359 void *gcry_calloc_secure (size_t n, size_t m) _GCRY_GCC_ATTR_MALLOC;
1360 void *gcry_realloc (void *a, size_t n);
1361 char *gcry_strdup (const char *string) _GCRY_GCC_ATTR_MALLOC;
1362 void *gcry_xmalloc (size_t n) _GCRY_GCC_ATTR_MALLOC;
1363 void *gcry_xcalloc (size_t n, size_t m) _GCRY_GCC_ATTR_MALLOC;
1364 void *gcry_xmalloc_secure (size_t n) _GCRY_GCC_ATTR_MALLOC;
1365 void *gcry_xcalloc_secure (size_t n, size_t m) _GCRY_GCC_ATTR_MALLOC;
1366 void *gcry_xrealloc (void *a, size_t n);
1367 char *gcry_xstrdup (const char * a) _GCRY_GCC_ATTR_MALLOC;
1368 void  gcry_free (void *a);
1369
1370 /* Return true if A is allocated in "secure" memory. */
1371 int gcry_is_secure (const void *a) _GCRY_GCC_ATTR_PURE;
1372
1373 #if 0 /* keep Emacsens's auto-indent happy */
1374 {
1375 #endif
1376 #ifdef __cplusplus
1377 }
1378 #endif
1379 #endif /* _GCRYPT_H */