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