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