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