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