Line data Source code
1 : /* gcrypt.h - GNU Cryptographic Library Interface -*- c -*-
2 : * Copyright (C) 1998-2016 Free Software Foundation, Inc.
3 : * Copyright (C) 2012-2016 g10 Code GmbH
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: src/gcrypt.h. Generated from gcrypt.h.in by configure.
21 : */
22 :
23 : #ifndef _GCRYPT_H
24 : #define _GCRYPT_H
25 :
26 : #include <stdlib.h>
27 : #include <stdarg.h>
28 : #include <string.h>
29 :
30 : #include <gpg-error.h>
31 :
32 : #include <sys/types.h>
33 :
34 : #if defined _WIN32 || defined __WIN32__
35 : # include <winsock2.h>
36 : # include <ws2tcpip.h>
37 : # include <time.h>
38 : # ifndef __GNUC__
39 : typedef long ssize_t;
40 : typedef int pid_t;
41 : # endif /*!__GNUC__*/
42 : #else
43 : # include <sys/socket.h>
44 : # include <sys/time.h>
45 : # include <sys/select.h>
46 : #endif /*!_WIN32*/
47 :
48 : typedef socklen_t gcry_socklen_t;
49 :
50 : /* This is required for error code compatibility. */
51 : #define _GCRY_ERR_SOURCE_DEFAULT GPG_ERR_SOURCE_GCRYPT
52 :
53 : #ifdef __cplusplus
54 : extern "C" {
55 : #if 0 /* (Keep Emacsens' auto-indent happy.) */
56 : }
57 : #endif
58 : #endif
59 :
60 : /* The version of this header should match the one of the library. It
61 : should not be used by a program because gcry_check_version() should
62 : return the same version. The purpose of this macro is to let
63 : autoconf (using the AM_PATH_GCRYPT macro) check that this header
64 : matches the installed library. */
65 : #define GCRYPT_VERSION "1.8.0"
66 :
67 : /* The version number of this header. It may be used to handle minor
68 : API incompatibilities. */
69 : #define GCRYPT_VERSION_NUMBER 0x010800
70 :
71 :
72 : /* Internal: We can't use the convenience macros for the multi
73 : precision integer functions when building this library. */
74 : #ifdef _GCRYPT_IN_LIBGCRYPT
75 : #ifndef GCRYPT_NO_MPI_MACROS
76 : #define GCRYPT_NO_MPI_MACROS 1
77 : #endif
78 : #endif
79 :
80 : /* We want to use gcc attributes when possible. Warning: Don't use
81 : these macros in your programs: As indicated by the leading
82 : underscore they are subject to change without notice. */
83 : #ifdef __GNUC__
84 :
85 : #define _GCRY_GCC_VERSION (__GNUC__ * 10000 \
86 : + __GNUC_MINOR__ * 100 \
87 : + __GNUC_PATCHLEVEL__)
88 :
89 : #if _GCRY_GCC_VERSION >= 30100
90 : #define _GCRY_GCC_ATTR_DEPRECATED __attribute__ ((__deprecated__))
91 : #endif
92 :
93 : #if _GCRY_GCC_VERSION >= 29600
94 : #define _GCRY_GCC_ATTR_PURE __attribute__ ((__pure__))
95 : #endif
96 :
97 : #if _GCRY_GCC_VERSION >= 30200
98 : #define _GCRY_GCC_ATTR_MALLOC __attribute__ ((__malloc__))
99 : #endif
100 :
101 : #define _GCRY_GCC_ATTR_PRINTF(f,a) __attribute__ ((format (printf,f,a)))
102 :
103 : #if _GCRY_GCC_VERSION >= 40000
104 : #define _GCRY_GCC_ATTR_SENTINEL(a) __attribute__ ((sentinel(a)))
105 : #endif
106 :
107 : #endif /*__GNUC__*/
108 :
109 : #ifndef _GCRY_GCC_ATTR_DEPRECATED
110 : #define _GCRY_GCC_ATTR_DEPRECATED
111 : #endif
112 : #ifndef _GCRY_GCC_ATTR_PURE
113 : #define _GCRY_GCC_ATTR_PURE
114 : #endif
115 : #ifndef _GCRY_GCC_ATTR_MALLOC
116 : #define _GCRY_GCC_ATTR_MALLOC
117 : #endif
118 : #ifndef _GCRY_GCC_ATTR_PRINTF
119 : #define _GCRY_GCC_ATTR_PRINTF(f,a)
120 : #endif
121 : #ifndef _GCRY_GCC_ATTR_SENTINEL
122 : #define _GCRY_GCC_ATTR_SENTINEL(a)
123 : #endif
124 :
125 : /* Make up an attribute to mark functions and types as deprecated but
126 : allow internal use by Libgcrypt. */
127 : #ifdef _GCRYPT_IN_LIBGCRYPT
128 : #define _GCRY_ATTR_INTERNAL
129 : #else
130 : #define _GCRY_ATTR_INTERNAL _GCRY_GCC_ATTR_DEPRECATED
131 : #endif
132 :
133 : /* Wrappers for the libgpg-error library. */
134 :
135 : typedef gpg_error_t gcry_error_t;
136 : typedef gpg_err_code_t gcry_err_code_t;
137 : typedef gpg_err_source_t gcry_err_source_t;
138 :
139 : static GPG_ERR_INLINE gcry_error_t
140 184113 : gcry_err_make (gcry_err_source_t source, gcry_err_code_t code)
141 : {
142 184113 : return gpg_err_make (source, code);
143 : }
144 :
145 : /* The user can define GPG_ERR_SOURCE_DEFAULT before including this
146 : file to specify a default source for gpg_error. */
147 : #ifndef GCRY_ERR_SOURCE_DEFAULT
148 : #define GCRY_ERR_SOURCE_DEFAULT GPG_ERR_SOURCE_USER_1
149 : #endif
150 :
151 : static GPG_ERR_INLINE gcry_error_t
152 184113 : gcry_error (gcry_err_code_t code)
153 : {
154 184113 : return gcry_err_make (GCRY_ERR_SOURCE_DEFAULT, code);
155 : }
156 :
157 : static GPG_ERR_INLINE gcry_err_code_t
158 1249 : gcry_err_code (gcry_error_t err)
159 : {
160 1249 : return gpg_err_code (err);
161 : }
162 :
163 :
164 : static GPG_ERR_INLINE gcry_err_source_t
165 : gcry_err_source (gcry_error_t err)
166 : {
167 : return gpg_err_source (err);
168 : }
169 :
170 : /* Return a pointer to a string containing a description of the error
171 : code in the error value ERR. */
172 : const char *gcry_strerror (gcry_error_t err);
173 :
174 : /* Return a pointer to a string containing a description of the error
175 : source in the error value ERR. */
176 : const char *gcry_strsource (gcry_error_t err);
177 :
178 : /* Retrieve the error code for the system error ERR. This returns
179 : GPG_ERR_UNKNOWN_ERRNO if the system error is not mapped (report
180 : this). */
181 : gcry_err_code_t gcry_err_code_from_errno (int err);
182 :
183 : /* Retrieve the system error for the error code CODE. This returns 0
184 : if CODE is not a system error code. */
185 : int gcry_err_code_to_errno (gcry_err_code_t code);
186 :
187 : /* Return an error value with the error source SOURCE and the system
188 : error ERR. */
189 : gcry_error_t gcry_err_make_from_errno (gcry_err_source_t source, int err);
190 :
191 : /* Return an error value with the system error ERR. */
192 : gcry_err_code_t gcry_error_from_errno (int err);
193 :
194 :
195 : /* NOTE: Since Libgcrypt 1.6 the thread callbacks are not anymore
196 : used. However we keep it to allow for some source code
197 : compatibility if used in the standard way. */
198 :
199 : /* Constants defining the thread model to use. Used with the OPTION
200 : field of the struct gcry_thread_cbs. */
201 : #define GCRY_THREAD_OPTION_DEFAULT 0
202 : #define GCRY_THREAD_OPTION_USER 1
203 : #define GCRY_THREAD_OPTION_PTH 2
204 : #define GCRY_THREAD_OPTION_PTHREAD 3
205 :
206 : /* The version number encoded in the OPTION field of the struct
207 : gcry_thread_cbs. */
208 : #define GCRY_THREAD_OPTION_VERSION 1
209 :
210 : /* Wrapper for struct ath_ops. */
211 : struct gcry_thread_cbs
212 : {
213 : /* The OPTION field encodes the thread model and the version number
214 : of this structure.
215 : Bits 7 - 0 are used for the thread model
216 : Bits 15 - 8 are used for the version number. */
217 : unsigned int option;
218 : } _GCRY_ATTR_INTERNAL;
219 :
220 : #define GCRY_THREAD_OPTION_PTH_IMPL \
221 : static struct gcry_thread_cbs gcry_threads_pth = { \
222 : (GCRY_THREAD_OPTION_PTH | (GCRY_THREAD_OPTION_VERSION << 8))}
223 :
224 : #define GCRY_THREAD_OPTION_PTHREAD_IMPL \
225 : static struct gcry_thread_cbs gcry_threads_pthread = { \
226 : (GCRY_THREAD_OPTION_PTHREAD | (GCRY_THREAD_OPTION_VERSION << 8))}
227 :
228 :
229 :
230 : /* A generic context object as used by some functions. */
231 : struct gcry_context;
232 : typedef struct gcry_context *gcry_ctx_t;
233 :
234 : /* The data objects used to hold multi precision integers. */
235 : struct gcry_mpi;
236 : typedef struct gcry_mpi *gcry_mpi_t;
237 : struct gcry_mpi_point;
238 : typedef struct gcry_mpi_point *gcry_mpi_point_t;
239 :
240 : #ifndef GCRYPT_NO_DEPRECATED
241 : typedef struct gcry_mpi *GCRY_MPI _GCRY_GCC_ATTR_DEPRECATED;
242 : typedef struct gcry_mpi *GcryMPI _GCRY_GCC_ATTR_DEPRECATED;
243 : #endif
244 :
245 : /* A structure used for scatter gather hashing. */
246 : typedef struct
247 : {
248 : size_t size; /* The allocated size of the buffer or 0. */
249 : size_t off; /* Offset into the buffer. */
250 : size_t len; /* The used length of the buffer. */
251 : void *data; /* The buffer. */
252 : } gcry_buffer_t;
253 :
254 :
255 :
256 :
257 : /* Check that the library fulfills the version requirement. */
258 : const char *gcry_check_version (const char *req_version);
259 :
260 : /* Codes for function dispatchers. */
261 :
262 : /* Codes used with the gcry_control function. */
263 : enum gcry_ctl_cmds
264 : {
265 : /* Note: 1 .. 2 are not anymore used. */
266 : GCRYCTL_CFB_SYNC = 3,
267 : GCRYCTL_RESET = 4, /* e.g. for MDs */
268 : GCRYCTL_FINALIZE = 5,
269 : GCRYCTL_GET_KEYLEN = 6,
270 : GCRYCTL_GET_BLKLEN = 7,
271 : GCRYCTL_TEST_ALGO = 8,
272 : GCRYCTL_IS_SECURE = 9,
273 : GCRYCTL_GET_ASNOID = 10,
274 : GCRYCTL_ENABLE_ALGO = 11,
275 : GCRYCTL_DISABLE_ALGO = 12,
276 : GCRYCTL_DUMP_RANDOM_STATS = 13,
277 : GCRYCTL_DUMP_SECMEM_STATS = 14,
278 : GCRYCTL_GET_ALGO_NPKEY = 15,
279 : GCRYCTL_GET_ALGO_NSKEY = 16,
280 : GCRYCTL_GET_ALGO_NSIGN = 17,
281 : GCRYCTL_GET_ALGO_NENCR = 18,
282 : GCRYCTL_SET_VERBOSITY = 19,
283 : GCRYCTL_SET_DEBUG_FLAGS = 20,
284 : GCRYCTL_CLEAR_DEBUG_FLAGS = 21,
285 : GCRYCTL_USE_SECURE_RNDPOOL= 22,
286 : GCRYCTL_DUMP_MEMORY_STATS = 23,
287 : GCRYCTL_INIT_SECMEM = 24,
288 : GCRYCTL_TERM_SECMEM = 25,
289 : GCRYCTL_DISABLE_SECMEM_WARN = 27,
290 : GCRYCTL_SUSPEND_SECMEM_WARN = 28,
291 : GCRYCTL_RESUME_SECMEM_WARN = 29,
292 : GCRYCTL_DROP_PRIVS = 30,
293 : GCRYCTL_ENABLE_M_GUARD = 31,
294 : GCRYCTL_START_DUMP = 32,
295 : GCRYCTL_STOP_DUMP = 33,
296 : GCRYCTL_GET_ALGO_USAGE = 34,
297 : GCRYCTL_IS_ALGO_ENABLED = 35,
298 : GCRYCTL_DISABLE_INTERNAL_LOCKING = 36,
299 : GCRYCTL_DISABLE_SECMEM = 37,
300 : GCRYCTL_INITIALIZATION_FINISHED = 38,
301 : GCRYCTL_INITIALIZATION_FINISHED_P = 39,
302 : GCRYCTL_ANY_INITIALIZATION_P = 40,
303 : GCRYCTL_SET_CBC_CTS = 41,
304 : GCRYCTL_SET_CBC_MAC = 42,
305 : /* Note: 43 is not anymore used. */
306 : GCRYCTL_ENABLE_QUICK_RANDOM = 44,
307 : GCRYCTL_SET_RANDOM_SEED_FILE = 45,
308 : GCRYCTL_UPDATE_RANDOM_SEED_FILE = 46,
309 : GCRYCTL_SET_THREAD_CBS = 47,
310 : GCRYCTL_FAST_POLL = 48,
311 : GCRYCTL_SET_RANDOM_DAEMON_SOCKET = 49,
312 : GCRYCTL_USE_RANDOM_DAEMON = 50,
313 : GCRYCTL_FAKED_RANDOM_P = 51,
314 : GCRYCTL_SET_RNDEGD_SOCKET = 52,
315 : GCRYCTL_PRINT_CONFIG = 53,
316 : GCRYCTL_OPERATIONAL_P = 54,
317 : GCRYCTL_FIPS_MODE_P = 55,
318 : GCRYCTL_FORCE_FIPS_MODE = 56,
319 : GCRYCTL_SELFTEST = 57,
320 : /* Note: 58 .. 62 are used internally. */
321 : GCRYCTL_DISABLE_HWF = 63,
322 : GCRYCTL_SET_ENFORCED_FIPS_FLAG = 64,
323 : GCRYCTL_SET_PREFERRED_RNG_TYPE = 65,
324 : GCRYCTL_GET_CURRENT_RNG_TYPE = 66,
325 : GCRYCTL_DISABLE_LOCKED_SECMEM = 67,
326 : GCRYCTL_DISABLE_PRIV_DROP = 68,
327 : GCRYCTL_SET_CCM_LENGTHS = 69,
328 : GCRYCTL_CLOSE_RANDOM_DEVICE = 70,
329 : GCRYCTL_INACTIVATE_FIPS_FLAG = 71,
330 : GCRYCTL_REACTIVATE_FIPS_FLAG = 72,
331 : GCRYCTL_SET_SBOX = 73,
332 : GCRYCTL_DRBG_REINIT = 74,
333 : GCRYCTL_SET_TAGLEN = 75,
334 : GCRYCTL_GET_TAGLEN = 76,
335 : GCRYCTL_REINIT_SYSCALL_CLAMP = 77
336 : };
337 :
338 : /* Perform various operations defined by CMD. */
339 : gcry_error_t gcry_control (enum gcry_ctl_cmds CMD, ...);
340 :
341 :
342 : /* S-expression management. */
343 :
344 : /* The object to represent an S-expression as used with the public key
345 : functions. */
346 : struct gcry_sexp;
347 : typedef struct gcry_sexp *gcry_sexp_t;
348 :
349 : #ifndef GCRYPT_NO_DEPRECATED
350 : typedef struct gcry_sexp *GCRY_SEXP _GCRY_GCC_ATTR_DEPRECATED;
351 : typedef struct gcry_sexp *GcrySexp _GCRY_GCC_ATTR_DEPRECATED;
352 : #endif
353 :
354 : /* The possible values for the S-expression format. */
355 : enum gcry_sexp_format
356 : {
357 : GCRYSEXP_FMT_DEFAULT = 0,
358 : GCRYSEXP_FMT_CANON = 1,
359 : GCRYSEXP_FMT_BASE64 = 2,
360 : GCRYSEXP_FMT_ADVANCED = 3
361 : };
362 :
363 : /* Create an new S-expression object from BUFFER of size LENGTH and
364 : return it in RETSEXP. With AUTODETECT set to 0 the data in BUFFER
365 : is expected to be in canonized format. */
366 : gcry_error_t gcry_sexp_new (gcry_sexp_t *retsexp,
367 : const void *buffer, size_t length,
368 : int autodetect);
369 :
370 : /* Same as gcry_sexp_new but allows to pass a FREEFNC which has the
371 : effect to transfer ownership of BUFFER to the created object. */
372 : gcry_error_t gcry_sexp_create (gcry_sexp_t *retsexp,
373 : void *buffer, size_t length,
374 : int autodetect, void (*freefnc) (void *));
375 :
376 : /* Scan BUFFER and return a new S-expression object in RETSEXP. This
377 : function expects a printf like string in BUFFER. */
378 : gcry_error_t gcry_sexp_sscan (gcry_sexp_t *retsexp, size_t *erroff,
379 : const char *buffer, size_t length);
380 :
381 : /* Same as gcry_sexp_sscan but expects a string in FORMAT and can thus
382 : only be used for certain encodings. */
383 : gcry_error_t gcry_sexp_build (gcry_sexp_t *retsexp, size_t *erroff,
384 : const char *format, ...);
385 :
386 : /* Like gcry_sexp_build, but uses an array instead of variable
387 : function arguments. */
388 : gcry_error_t gcry_sexp_build_array (gcry_sexp_t *retsexp, size_t *erroff,
389 : const char *format, void **arg_list);
390 :
391 : /* Release the S-expression object SEXP */
392 : void gcry_sexp_release (gcry_sexp_t sexp);
393 :
394 : /* Calculate the length of an canonized S-expresion in BUFFER and
395 : check for a valid encoding. */
396 : size_t gcry_sexp_canon_len (const unsigned char *buffer, size_t length,
397 : size_t *erroff, gcry_error_t *errcode);
398 :
399 : /* Copies the S-expression object SEXP into BUFFER using the format
400 : specified in MODE. */
401 : size_t gcry_sexp_sprint (gcry_sexp_t sexp, int mode, void *buffer,
402 : size_t maxlength);
403 :
404 : /* Dumps the S-expression object A in a format suitable for debugging
405 : to Libgcrypt's logging stream. */
406 : void gcry_sexp_dump (const gcry_sexp_t a);
407 :
408 : gcry_sexp_t gcry_sexp_cons (const gcry_sexp_t a, const gcry_sexp_t b);
409 : gcry_sexp_t gcry_sexp_alist (const gcry_sexp_t *array);
410 : gcry_sexp_t gcry_sexp_vlist (const gcry_sexp_t a, ...);
411 : gcry_sexp_t gcry_sexp_append (const gcry_sexp_t a, const gcry_sexp_t n);
412 : gcry_sexp_t gcry_sexp_prepend (const gcry_sexp_t a, const gcry_sexp_t n);
413 :
414 : /* Scan the S-expression for a sublist with a type (the car of the
415 : list) matching the string TOKEN. If TOKLEN is not 0, the token is
416 : assumed to be raw memory of this length. The function returns a
417 : newly allocated S-expression consisting of the found sublist or
418 : `NULL' when not found. */
419 : gcry_sexp_t gcry_sexp_find_token (gcry_sexp_t list,
420 : const char *tok, size_t toklen);
421 : /* Return the length of the LIST. For a valid S-expression this
422 : should be at least 1. */
423 : int gcry_sexp_length (const gcry_sexp_t list);
424 :
425 : /* Create and return a new S-expression from the element with index
426 : NUMBER in LIST. Note that the first element has the index 0. If
427 : there is no such element, `NULL' is returned. */
428 : gcry_sexp_t gcry_sexp_nth (const gcry_sexp_t list, int number);
429 :
430 : /* Create and return a new S-expression from the first element in
431 : LIST; this called the "type" and should always exist and be a
432 : string. `NULL' is returned in case of a problem. */
433 : gcry_sexp_t gcry_sexp_car (const gcry_sexp_t list);
434 :
435 : /* Create and return a new list form all elements except for the first
436 : one. Note, that this function may return an invalid S-expression
437 : because it is not guaranteed, that the type exists and is a string.
438 : However, for parsing a complex S-expression it might be useful for
439 : intermediate lists. Returns `NULL' on error. */
440 : gcry_sexp_t gcry_sexp_cdr (const gcry_sexp_t list);
441 :
442 : gcry_sexp_t gcry_sexp_cadr (const gcry_sexp_t list);
443 :
444 :
445 : /* This function is used to get data from a LIST. A pointer to the
446 : actual data with index NUMBER is returned and the length of this
447 : data will be stored to DATALEN. If there is no data at the given
448 : index or the index represents another list, `NULL' is returned.
449 : *Note:* The returned pointer is valid as long as LIST is not
450 : modified or released. */
451 : const char *gcry_sexp_nth_data (const gcry_sexp_t list, int number,
452 : size_t *datalen);
453 :
454 : /* This function is used to get data from a LIST. A malloced buffer to the
455 : data with index NUMBER is returned and the length of this
456 : data will be stored to RLENGTH. If there is no data at the given
457 : index or the index represents another list, `NULL' is returned. */
458 : void *gcry_sexp_nth_buffer (const gcry_sexp_t list, int number,
459 : size_t *rlength);
460 :
461 : /* This function is used to get and convert data from a LIST. The
462 : data is assumed to be a Nul terminated string. The caller must
463 : release the returned value using `gcry_free'. If there is no data
464 : at the given index, the index represents a list or the value can't
465 : be converted to a string, `NULL' is returned. */
466 : char *gcry_sexp_nth_string (gcry_sexp_t list, int number);
467 :
468 : /* This function is used to get and convert data from a LIST. This
469 : data is assumed to be an MPI stored in the format described by
470 : MPIFMT and returned as a standard Libgcrypt MPI. The caller must
471 : release this returned value using `gcry_mpi_release'. If there is
472 : no data at the given index, the index represents a list or the
473 : value can't be converted to an MPI, `NULL' is returned. */
474 : gcry_mpi_t gcry_sexp_nth_mpi (gcry_sexp_t list, int number, int mpifmt);
475 :
476 : /* Extract MPIs from an s-expression using a list of parameters. The
477 : * names of these parameters are given by the string LIST. Some
478 : * special characters may be given to control the conversion:
479 : *
480 : * + :: Switch to unsigned integer format (default).
481 : * - :: Switch to standard signed format.
482 : * / :: Switch to opaque format.
483 : * & :: Switch to buffer descriptor mode - see below.
484 : * ? :: The previous parameter is optional.
485 : *
486 : * In general parameter names are single letters. To use a string for
487 : * a parameter name, enclose the name in single quotes.
488 : *
489 : * Unless in gcry_buffer_t mode for each parameter name a pointer to
490 : * an MPI variable is expected that must be set to NULL prior to
491 : * invoking this function, and finally a NULL is expected. Example:
492 : *
493 : * _gcry_sexp_extract_param (key, NULL, "n/x+ed",
494 : * &mpi_n, &mpi_x, &mpi_e, NULL)
495 : *
496 : * This stores the parameter "N" from KEY as an unsigned MPI into
497 : * MPI_N, the parameter "X" as an opaque MPI into MPI_X, and the
498 : * parameter "E" again as an unsigned MPI into MPI_E.
499 : *
500 : * If in buffer descriptor mode a pointer to gcry_buffer_t descriptor
501 : * is expected instead of a pointer to an MPI. The caller may use two
502 : * different operation modes: If the DATA field of the provided buffer
503 : * descriptor is NULL, the function allocates a new buffer and stores
504 : * it at DATA; the other fields are set accordingly with OFF being 0.
505 : * If DATA is not NULL, the function assumes that DATA, SIZE, and OFF
506 : * describe a buffer where to but the data; on return the LEN field
507 : * receives the number of bytes copied to that buffer; if the buffer
508 : * is too small, the function immediately returns with an error code
509 : * (and LEN set to 0).
510 : *
511 : * PATH is an optional string used to locate a token. The exclamation
512 : * mark separated tokens are used to via gcry_sexp_find_token to find
513 : * a start point inside SEXP.
514 : *
515 : * The function returns 0 on success. On error an error code is
516 : * returned, all passed MPIs that might have been allocated up to this
517 : * point are deallocated and set to NULL, and all passed buffers are
518 : * either truncated if the caller supplied the buffer, or deallocated
519 : * if the function allocated the buffer.
520 : */
521 : gpg_error_t gcry_sexp_extract_param (gcry_sexp_t sexp,
522 : const char *path,
523 : const char *list,
524 : ...) _GCRY_GCC_ATTR_SENTINEL(0);
525 :
526 :
527 : /*******************************************
528 : * *
529 : * Multi Precision Integer Functions *
530 : * *
531 : *******************************************/
532 :
533 : /* Different formats of external big integer representation. */
534 : enum gcry_mpi_format
535 : {
536 : GCRYMPI_FMT_NONE= 0,
537 : GCRYMPI_FMT_STD = 1, /* Twos complement stored without length. */
538 : GCRYMPI_FMT_PGP = 2, /* As used by OpenPGP (unsigned only). */
539 : GCRYMPI_FMT_SSH = 3, /* As used by SSH (like STD but with length). */
540 : GCRYMPI_FMT_HEX = 4, /* Hex format. */
541 : GCRYMPI_FMT_USG = 5, /* Like STD but unsigned. */
542 : GCRYMPI_FMT_OPAQUE = 8 /* Opaque format (some functions only). */
543 : };
544 :
545 : /* Flags used for creating big integers. */
546 : enum gcry_mpi_flag
547 : {
548 : GCRYMPI_FLAG_SECURE = 1, /* Allocate the number in "secure" memory. */
549 : GCRYMPI_FLAG_OPAQUE = 2, /* The number is not a real one but just
550 : a way to store some bytes. This is
551 : useful for encrypted big integers. */
552 : GCRYMPI_FLAG_IMMUTABLE = 4, /* Mark the MPI as immutable. */
553 : GCRYMPI_FLAG_CONST = 8, /* Mark the MPI as a constant. */
554 : GCRYMPI_FLAG_USER1 = 0x0100,/* User flag 1. */
555 : GCRYMPI_FLAG_USER2 = 0x0200,/* User flag 2. */
556 : GCRYMPI_FLAG_USER3 = 0x0400,/* User flag 3. */
557 : GCRYMPI_FLAG_USER4 = 0x0800 /* User flag 4. */
558 : };
559 :
560 :
561 : /* Macros to return pre-defined MPI constants. */
562 : #define GCRYMPI_CONST_ONE (_gcry_mpi_get_const (1))
563 : #define GCRYMPI_CONST_TWO (_gcry_mpi_get_const (2))
564 : #define GCRYMPI_CONST_THREE (_gcry_mpi_get_const (3))
565 : #define GCRYMPI_CONST_FOUR (_gcry_mpi_get_const (4))
566 : #define GCRYMPI_CONST_EIGHT (_gcry_mpi_get_const (8))
567 :
568 : /* Allocate a new big integer object, initialize it with 0 and
569 : initially allocate memory for a number of at least NBITS. */
570 : gcry_mpi_t gcry_mpi_new (unsigned int nbits);
571 :
572 : /* Same as gcry_mpi_new() but allocate in "secure" memory. */
573 : gcry_mpi_t gcry_mpi_snew (unsigned int nbits);
574 :
575 : /* Release the number A and free all associated resources. */
576 : void gcry_mpi_release (gcry_mpi_t a);
577 :
578 : /* Create a new number with the same value as A. */
579 : gcry_mpi_t gcry_mpi_copy (const gcry_mpi_t a);
580 :
581 : /* Store the big integer value U in W and release U. */
582 : void gcry_mpi_snatch (gcry_mpi_t w, gcry_mpi_t u);
583 :
584 : /* Store the big integer value U in W. */
585 : gcry_mpi_t gcry_mpi_set (gcry_mpi_t w, const gcry_mpi_t u);
586 :
587 : /* Store the unsigned integer value U in W. */
588 : gcry_mpi_t gcry_mpi_set_ui (gcry_mpi_t w, unsigned long u);
589 :
590 : /* Swap the values of A and B. */
591 : void gcry_mpi_swap (gcry_mpi_t a, gcry_mpi_t b);
592 :
593 : /* Return 1 if A is negative; 0 if zero or positive. */
594 : int gcry_mpi_is_neg (gcry_mpi_t a);
595 :
596 : /* W = - U */
597 : void gcry_mpi_neg (gcry_mpi_t w, gcry_mpi_t u);
598 :
599 : /* W = [W] */
600 : void gcry_mpi_abs (gcry_mpi_t w);
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 into 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 : /* Create a new point object. NBITS is usually 0. */
696 : gcry_mpi_point_t gcry_mpi_point_new (unsigned int nbits);
697 :
698 : /* Release the object POINT. POINT may be NULL. */
699 : void gcry_mpi_point_release (gcry_mpi_point_t point);
700 :
701 : /* Store the projective coordinates from POINT into X, Y, and Z. */
702 : void gcry_mpi_point_get (gcry_mpi_t x, gcry_mpi_t y, gcry_mpi_t z,
703 : gcry_mpi_point_t point);
704 :
705 : /* Store the projective coordinates from POINT into X, Y, and Z and
706 : release POINT. */
707 : void gcry_mpi_point_snatch_get (gcry_mpi_t x, gcry_mpi_t y, gcry_mpi_t z,
708 : gcry_mpi_point_t point);
709 :
710 : /* Store the projective coordinates X, Y, and Z into POINT. */
711 : gcry_mpi_point_t gcry_mpi_point_set (gcry_mpi_point_t point,
712 : gcry_mpi_t x, gcry_mpi_t y, gcry_mpi_t z);
713 :
714 : /* Store the projective coordinates X, Y, and Z into POINT and release
715 : X, Y, and Z. */
716 : gcry_mpi_point_t gcry_mpi_point_snatch_set (gcry_mpi_point_t point,
717 : gcry_mpi_t x, gcry_mpi_t y,
718 : gcry_mpi_t z);
719 :
720 : /* Allocate a new context for elliptic curve operations based on the
721 : parameters given by KEYPARAM or using CURVENAME. */
722 : gpg_error_t gcry_mpi_ec_new (gcry_ctx_t *r_ctx,
723 : gcry_sexp_t keyparam, const char *curvename);
724 :
725 : /* Get a named MPI from an elliptic curve context. */
726 : gcry_mpi_t gcry_mpi_ec_get_mpi (const char *name, gcry_ctx_t ctx, int copy);
727 :
728 : /* Get a named point from an elliptic curve context. */
729 : gcry_mpi_point_t gcry_mpi_ec_get_point (const char *name,
730 : gcry_ctx_t ctx, int copy);
731 :
732 : /* Store a named MPI into an elliptic curve context. */
733 : gpg_error_t gcry_mpi_ec_set_mpi (const char *name, gcry_mpi_t newvalue,
734 : gcry_ctx_t ctx);
735 :
736 : /* Store a named point into an elliptic curve context. */
737 : gpg_error_t gcry_mpi_ec_set_point (const char *name, gcry_mpi_point_t newvalue,
738 : gcry_ctx_t ctx);
739 :
740 : /* Decode and store VALUE into RESULT. */
741 : gpg_error_t gcry_mpi_ec_decode_point (gcry_mpi_point_t result,
742 : gcry_mpi_t value, gcry_ctx_t ctx);
743 :
744 : /* Store the affine coordinates of POINT into X and Y. */
745 : int gcry_mpi_ec_get_affine (gcry_mpi_t x, gcry_mpi_t y, gcry_mpi_point_t point,
746 : gcry_ctx_t ctx);
747 :
748 : /* W = 2 * U. */
749 : void gcry_mpi_ec_dup (gcry_mpi_point_t w, gcry_mpi_point_t u, gcry_ctx_t ctx);
750 :
751 : /* W = U + V. */
752 : void gcry_mpi_ec_add (gcry_mpi_point_t w,
753 : gcry_mpi_point_t u, gcry_mpi_point_t v, gcry_ctx_t ctx);
754 :
755 : /* W = U - V. */
756 : void gcry_mpi_ec_sub (gcry_mpi_point_t w,
757 : gcry_mpi_point_t u, gcry_mpi_point_t v, gcry_ctx_t ctx);
758 :
759 : /* W = N * U. */
760 : void gcry_mpi_ec_mul (gcry_mpi_point_t w, gcry_mpi_t n, gcry_mpi_point_t u,
761 : gcry_ctx_t ctx);
762 :
763 : /* Return true if POINT is on the curve described by CTX. */
764 : int gcry_mpi_ec_curve_point (gcry_mpi_point_t w, gcry_ctx_t ctx);
765 :
766 : /* Return the number of bits required to represent A. */
767 : unsigned int gcry_mpi_get_nbits (gcry_mpi_t a);
768 :
769 : /* Return true when bit number N (counting from 0) is set in A. */
770 : int gcry_mpi_test_bit (gcry_mpi_t a, unsigned int n);
771 :
772 : /* Set bit number N in A. */
773 : void gcry_mpi_set_bit (gcry_mpi_t a, unsigned int n);
774 :
775 : /* Clear bit number N in A. */
776 : void gcry_mpi_clear_bit (gcry_mpi_t a, unsigned int n);
777 :
778 : /* Set bit number N in A and clear all bits greater than N. */
779 : void gcry_mpi_set_highbit (gcry_mpi_t a, unsigned int n);
780 :
781 : /* Clear bit number N in A and all bits greater than N. */
782 : void gcry_mpi_clear_highbit (gcry_mpi_t a, unsigned int n);
783 :
784 : /* Shift the value of A by N bits to the right and store the result in X. */
785 : void gcry_mpi_rshift (gcry_mpi_t x, gcry_mpi_t a, unsigned int n);
786 :
787 : /* Shift the value of A by N bits to the left and store the result in X. */
788 : void gcry_mpi_lshift (gcry_mpi_t x, gcry_mpi_t a, unsigned int n);
789 :
790 : /* Store NBITS of the value P points to in A and mark A as an opaque
791 : value. On success A received the the ownership of the value P.
792 : WARNING: Never use an opaque MPI for anything thing else than
793 : gcry_mpi_release, gcry_mpi_get_opaque. */
794 : gcry_mpi_t gcry_mpi_set_opaque (gcry_mpi_t a, void *p, unsigned int nbits);
795 :
796 : /* Store NBITS of the value P points to in A and mark A as an opaque
797 : value. The function takes a copy of the provided value P.
798 : WARNING: Never use an opaque MPI for anything thing else than
799 : gcry_mpi_release, gcry_mpi_get_opaque. */
800 : gcry_mpi_t gcry_mpi_set_opaque_copy (gcry_mpi_t a,
801 : const void *p, unsigned int nbits);
802 :
803 : /* Return a pointer to an opaque value stored in A and return its size
804 : in NBITS. Note that the returned pointer is still owned by A and
805 : that the function should never be used for an non-opaque MPI. */
806 : void *gcry_mpi_get_opaque (gcry_mpi_t a, unsigned int *nbits);
807 :
808 : /* Set the FLAG for the big integer A. Currently only the flag
809 : GCRYMPI_FLAG_SECURE is allowed to convert A into an big intger
810 : stored in "secure" memory. */
811 : void gcry_mpi_set_flag (gcry_mpi_t a, enum gcry_mpi_flag flag);
812 :
813 : /* Clear FLAG for the big integer A. Note that this function is
814 : currently useless as no flags are allowed. */
815 : void gcry_mpi_clear_flag (gcry_mpi_t a, enum gcry_mpi_flag flag);
816 :
817 : /* Return true if the FLAG is set for A. */
818 : int gcry_mpi_get_flag (gcry_mpi_t a, enum gcry_mpi_flag flag);
819 :
820 : /* Private function - do not use. */
821 : gcry_mpi_t _gcry_mpi_get_const (int no);
822 :
823 : /* Unless the GCRYPT_NO_MPI_MACROS is used, provide a couple of
824 : convenience macros for the big integer functions. */
825 : #ifndef GCRYPT_NO_MPI_MACROS
826 : #define mpi_new(n) gcry_mpi_new( (n) )
827 : #define mpi_secure_new( n ) gcry_mpi_snew( (n) )
828 : #define mpi_release(a) \
829 : do \
830 : { \
831 : gcry_mpi_release ((a)); \
832 : (a) = NULL; \
833 : } \
834 : while (0)
835 :
836 : #define mpi_copy( a ) gcry_mpi_copy( (a) )
837 : #define mpi_snatch( w, u) gcry_mpi_snatch( (w), (u) )
838 : #define mpi_set( w, u) gcry_mpi_set( (w), (u) )
839 : #define mpi_set_ui( w, u) gcry_mpi_set_ui( (w), (u) )
840 : #define mpi_abs( w ) gcry_mpi_abs( (w) )
841 : #define mpi_neg( w, u) gcry_mpi_neg( (w), (u) )
842 : #define mpi_cmp( u, v ) gcry_mpi_cmp( (u), (v) )
843 : #define mpi_cmp_ui( u, v ) gcry_mpi_cmp_ui( (u), (v) )
844 : #define mpi_is_neg( a ) gcry_mpi_is_neg ((a))
845 :
846 : #define mpi_add_ui(w,u,v) gcry_mpi_add_ui((w),(u),(v))
847 : #define mpi_add(w,u,v) gcry_mpi_add ((w),(u),(v))
848 : #define mpi_addm(w,u,v,m) gcry_mpi_addm ((w),(u),(v),(m))
849 : #define mpi_sub_ui(w,u,v) gcry_mpi_sub_ui ((w),(u),(v))
850 : #define mpi_sub(w,u,v) gcry_mpi_sub ((w),(u),(v))
851 : #define mpi_subm(w,u,v,m) gcry_mpi_subm ((w),(u),(v),(m))
852 : #define mpi_mul_ui(w,u,v) gcry_mpi_mul_ui ((w),(u),(v))
853 : #define mpi_mul_2exp(w,u,v) gcry_mpi_mul_2exp ((w),(u),(v))
854 : #define mpi_mul(w,u,v) gcry_mpi_mul ((w),(u),(v))
855 : #define mpi_mulm(w,u,v,m) gcry_mpi_mulm ((w),(u),(v),(m))
856 : #define mpi_powm(w,b,e,m) gcry_mpi_powm ( (w), (b), (e), (m) )
857 : #define mpi_tdiv(q,r,a,m) gcry_mpi_div ( (q), (r), (a), (m), 0)
858 : #define mpi_fdiv(q,r,a,m) gcry_mpi_div ( (q), (r), (a), (m), -1)
859 : #define mpi_mod(r,a,m) gcry_mpi_mod ((r), (a), (m))
860 : #define mpi_gcd(g,a,b) gcry_mpi_gcd ( (g), (a), (b) )
861 : #define mpi_invm(g,a,b) gcry_mpi_invm ( (g), (a), (b) )
862 :
863 : #define mpi_point_new(n) gcry_mpi_point_new((n))
864 : #define mpi_point_release(p) \
865 : do \
866 : { \
867 : gcry_mpi_point_release ((p)); \
868 : (p) = NULL; \
869 : } \
870 : while (0)
871 : #define mpi_point_get(x,y,z,p) gcry_mpi_point_get((x),(y),(z),(p))
872 : #define mpi_point_snatch_get(x,y,z,p) gcry_mpi_point_snatch_get((x),(y),(z),(p))
873 : #define mpi_point_set(p,x,y,z) gcry_mpi_point_set((p),(x),(y),(z))
874 : #define mpi_point_snatch_set(p,x,y,z) gcry_mpi_point_snatch_set((p),(x),(y),(z))
875 :
876 : #define mpi_get_nbits(a) gcry_mpi_get_nbits ((a))
877 : #define mpi_test_bit(a,b) gcry_mpi_test_bit ((a),(b))
878 : #define mpi_set_bit(a,b) gcry_mpi_set_bit ((a),(b))
879 : #define mpi_set_highbit(a,b) gcry_mpi_set_highbit ((a),(b))
880 : #define mpi_clear_bit(a,b) gcry_mpi_clear_bit ((a),(b))
881 : #define mpi_clear_highbit(a,b) gcry_mpi_clear_highbit ((a),(b))
882 : #define mpi_rshift(a,b,c) gcry_mpi_rshift ((a),(b),(c))
883 : #define mpi_lshift(a,b,c) gcry_mpi_lshift ((a),(b),(c))
884 :
885 : #define mpi_set_opaque(a,b,c) gcry_mpi_set_opaque( (a), (b), (c) )
886 : #define mpi_get_opaque(a,b) gcry_mpi_get_opaque( (a), (b) )
887 : #endif /* GCRYPT_NO_MPI_MACROS */
888 :
889 :
890 :
891 : /************************************
892 : * *
893 : * Symmetric Cipher Functions *
894 : * *
895 : ************************************/
896 :
897 : /* The data object used to hold a handle to an encryption object. */
898 : struct gcry_cipher_handle;
899 : typedef struct gcry_cipher_handle *gcry_cipher_hd_t;
900 :
901 : #ifndef GCRYPT_NO_DEPRECATED
902 : typedef struct gcry_cipher_handle *GCRY_CIPHER_HD _GCRY_GCC_ATTR_DEPRECATED;
903 : typedef struct gcry_cipher_handle *GcryCipherHd _GCRY_GCC_ATTR_DEPRECATED;
904 : #endif
905 :
906 : /* All symmetric encryption algorithms are identified by their IDs.
907 : More IDs may be registered at runtime. */
908 : enum gcry_cipher_algos
909 : {
910 : GCRY_CIPHER_NONE = 0,
911 : GCRY_CIPHER_IDEA = 1,
912 : GCRY_CIPHER_3DES = 2,
913 : GCRY_CIPHER_CAST5 = 3,
914 : GCRY_CIPHER_BLOWFISH = 4,
915 : GCRY_CIPHER_SAFER_SK128 = 5,
916 : GCRY_CIPHER_DES_SK = 6,
917 : GCRY_CIPHER_AES = 7,
918 : GCRY_CIPHER_AES192 = 8,
919 : GCRY_CIPHER_AES256 = 9,
920 : GCRY_CIPHER_TWOFISH = 10,
921 :
922 : /* Other cipher numbers are above 300 for OpenPGP reasons. */
923 : GCRY_CIPHER_ARCFOUR = 301, /* Fully compatible with RSA's RC4 (tm). */
924 : GCRY_CIPHER_DES = 302, /* Yes, this is single key 56 bit DES. */
925 : GCRY_CIPHER_TWOFISH128 = 303,
926 : GCRY_CIPHER_SERPENT128 = 304,
927 : GCRY_CIPHER_SERPENT192 = 305,
928 : GCRY_CIPHER_SERPENT256 = 306,
929 : GCRY_CIPHER_RFC2268_40 = 307, /* Ron's Cipher 2 (40 bit). */
930 : GCRY_CIPHER_RFC2268_128 = 308, /* Ron's Cipher 2 (128 bit). */
931 : GCRY_CIPHER_SEED = 309, /* 128 bit cipher described in RFC4269. */
932 : GCRY_CIPHER_CAMELLIA128 = 310,
933 : GCRY_CIPHER_CAMELLIA192 = 311,
934 : GCRY_CIPHER_CAMELLIA256 = 312,
935 : GCRY_CIPHER_SALSA20 = 313,
936 : GCRY_CIPHER_SALSA20R12 = 314,
937 : GCRY_CIPHER_GOST28147 = 315,
938 : GCRY_CIPHER_CHACHA20 = 316
939 : };
940 :
941 : /* The Rijndael algorithm is basically AES, so provide some macros. */
942 : #define GCRY_CIPHER_AES128 GCRY_CIPHER_AES
943 : #define GCRY_CIPHER_RIJNDAEL GCRY_CIPHER_AES
944 : #define GCRY_CIPHER_RIJNDAEL128 GCRY_CIPHER_AES128
945 : #define GCRY_CIPHER_RIJNDAEL192 GCRY_CIPHER_AES192
946 : #define GCRY_CIPHER_RIJNDAEL256 GCRY_CIPHER_AES256
947 :
948 : /* The supported encryption modes. Note that not all of them are
949 : supported for each algorithm. */
950 : enum gcry_cipher_modes
951 : {
952 : GCRY_CIPHER_MODE_NONE = 0, /* Not yet specified. */
953 : GCRY_CIPHER_MODE_ECB = 1, /* Electronic codebook. */
954 : GCRY_CIPHER_MODE_CFB = 2, /* Cipher feedback. */
955 : GCRY_CIPHER_MODE_CBC = 3, /* Cipher block chaining. */
956 : GCRY_CIPHER_MODE_STREAM = 4, /* Used with stream ciphers. */
957 : GCRY_CIPHER_MODE_OFB = 5, /* Outer feedback. */
958 : GCRY_CIPHER_MODE_CTR = 6, /* Counter. */
959 : GCRY_CIPHER_MODE_AESWRAP = 7, /* AES-WRAP algorithm. */
960 : GCRY_CIPHER_MODE_CCM = 8, /* Counter with CBC-MAC. */
961 : GCRY_CIPHER_MODE_GCM = 9, /* Galois Counter Mode. */
962 : GCRY_CIPHER_MODE_POLY1305 = 10, /* Poly1305 based AEAD mode. */
963 : GCRY_CIPHER_MODE_OCB = 11, /* OCB3 mode. */
964 : GCRY_CIPHER_MODE_CFB8 = 12, /* Cipher feedback (8 bit mode). */
965 : GCRY_CIPHER_MODE_XTS = 13 /* XTS mode. */
966 : };
967 :
968 : /* Flags used with the open function. */
969 : enum gcry_cipher_flags
970 : {
971 : GCRY_CIPHER_SECURE = 1, /* Allocate in secure memory. */
972 : GCRY_CIPHER_ENABLE_SYNC = 2, /* Enable CFB sync mode. */
973 : GCRY_CIPHER_CBC_CTS = 4, /* Enable CBC cipher text stealing (CTS). */
974 : GCRY_CIPHER_CBC_MAC = 8 /* Enable CBC message auth. code (MAC). */
975 : };
976 :
977 : /* GCM works only with blocks of 128 bits */
978 : #define GCRY_GCM_BLOCK_LEN (128 / 8)
979 :
980 : /* CCM works only with blocks of 128 bits. */
981 : #define GCRY_CCM_BLOCK_LEN (128 / 8)
982 :
983 : /* OCB works only with blocks of 128 bits. */
984 : #define GCRY_OCB_BLOCK_LEN (128 / 8)
985 :
986 : /* XTS works only with blocks of 128 bits. */
987 : #define GCRY_XTS_BLOCK_LEN (128 / 8)
988 :
989 : /* Create a handle for algorithm ALGO to be used in MODE. FLAGS may
990 : be given as an bitwise OR of the gcry_cipher_flags values. */
991 : gcry_error_t gcry_cipher_open (gcry_cipher_hd_t *handle,
992 : int algo, int mode, unsigned int flags);
993 :
994 : /* Close the cipher handle H and release all resource. */
995 : void gcry_cipher_close (gcry_cipher_hd_t h);
996 :
997 : /* Perform various operations on the cipher object H. */
998 : gcry_error_t gcry_cipher_ctl (gcry_cipher_hd_t h, int cmd, void *buffer,
999 : size_t buflen);
1000 :
1001 : /* Retrieve various information about the cipher object H. */
1002 : gcry_error_t gcry_cipher_info (gcry_cipher_hd_t h, int what, void *buffer,
1003 : size_t *nbytes);
1004 :
1005 : /* Retrieve various information about the cipher algorithm ALGO. */
1006 : gcry_error_t gcry_cipher_algo_info (int algo, int what, void *buffer,
1007 : size_t *nbytes);
1008 :
1009 : /* Map the cipher algorithm whose ID is contained in ALGORITHM to a
1010 : string representation of the algorithm name. For unknown algorithm
1011 : IDs this function returns "?". */
1012 : const char *gcry_cipher_algo_name (int algorithm) _GCRY_GCC_ATTR_PURE;
1013 :
1014 : /* Map the algorithm name NAME to an cipher algorithm ID. Return 0 if
1015 : the algorithm name is not known. */
1016 : int gcry_cipher_map_name (const char *name) _GCRY_GCC_ATTR_PURE;
1017 :
1018 : /* Given an ASN.1 object identifier in standard IETF dotted decimal
1019 : format in STRING, return the encryption mode associated with that
1020 : OID or 0 if not known or applicable. */
1021 : int gcry_cipher_mode_from_oid (const char *string) _GCRY_GCC_ATTR_PURE;
1022 :
1023 : /* Encrypt the plaintext of size INLEN in IN using the cipher handle H
1024 : into the buffer OUT which has an allocated length of OUTSIZE. For
1025 : most algorithms it is possible to pass NULL for in and 0 for INLEN
1026 : and do a in-place decryption of the data provided in OUT. */
1027 : gcry_error_t gcry_cipher_encrypt (gcry_cipher_hd_t h,
1028 : void *out, size_t outsize,
1029 : const void *in, size_t inlen);
1030 :
1031 : /* The counterpart to gcry_cipher_encrypt. */
1032 : gcry_error_t gcry_cipher_decrypt (gcry_cipher_hd_t h,
1033 : void *out, size_t outsize,
1034 : const void *in, size_t inlen);
1035 :
1036 : /* Set KEY of length KEYLEN bytes for the cipher handle HD. */
1037 : gcry_error_t gcry_cipher_setkey (gcry_cipher_hd_t hd,
1038 : const void *key, size_t keylen);
1039 :
1040 :
1041 : /* Set initialization vector IV of length IVLEN for the cipher handle HD. */
1042 : gcry_error_t gcry_cipher_setiv (gcry_cipher_hd_t hd,
1043 : const void *iv, size_t ivlen);
1044 :
1045 : /* Provide additional authentication data for AEAD modes/ciphers. */
1046 : gcry_error_t gcry_cipher_authenticate (gcry_cipher_hd_t hd, const void *abuf,
1047 : size_t abuflen);
1048 :
1049 : /* Get authentication tag for AEAD modes/ciphers. */
1050 : gcry_error_t gcry_cipher_gettag (gcry_cipher_hd_t hd, void *outtag,
1051 : size_t taglen);
1052 :
1053 : /* Check authentication tag for AEAD modes/ciphers. */
1054 : gcry_error_t gcry_cipher_checktag (gcry_cipher_hd_t hd, const void *intag,
1055 : size_t taglen);
1056 :
1057 : /* Reset the handle to the state after open. */
1058 : #define gcry_cipher_reset(h) gcry_cipher_ctl ((h), GCRYCTL_RESET, NULL, 0)
1059 :
1060 : /* Perform the OpenPGP sync operation if this is enabled for the
1061 : cipher handle H. */
1062 : #define gcry_cipher_sync(h) gcry_cipher_ctl( (h), GCRYCTL_CFB_SYNC, NULL, 0)
1063 :
1064 : /* Enable or disable CTS in future calls to gcry_encrypt(). CBC mode only. */
1065 : #define gcry_cipher_cts(h,on) gcry_cipher_ctl( (h), GCRYCTL_SET_CBC_CTS, \
1066 : NULL, on )
1067 :
1068 : #define gcry_cipher_set_sbox(h,oid) gcry_cipher_ctl( (h), GCRYCTL_SET_SBOX, \
1069 : (void *) oid, 0);
1070 :
1071 : /* Indicate to the encrypt and decrypt functions that the next call
1072 : provides the final data. Only used with some modes. */
1073 : #define gcry_cipher_final(a) \
1074 : gcry_cipher_ctl ((a), GCRYCTL_FINALIZE, NULL, 0)
1075 :
1076 : /* Set counter for CTR mode. (CTR,CTRLEN) must denote a buffer of
1077 : block size length, or (NULL,0) to set the CTR to the all-zero block. */
1078 : gpg_error_t gcry_cipher_setctr (gcry_cipher_hd_t hd,
1079 : const void *ctr, size_t ctrlen);
1080 :
1081 : /* Retrieve the key length in bytes used with algorithm A. */
1082 : size_t gcry_cipher_get_algo_keylen (int algo);
1083 :
1084 : /* Retrieve the block length in bytes used with algorithm A. */
1085 : size_t gcry_cipher_get_algo_blklen (int algo);
1086 :
1087 : /* Return 0 if the algorithm A is available for use. */
1088 : #define gcry_cipher_test_algo(a) \
1089 : gcry_cipher_algo_info( (a), GCRYCTL_TEST_ALGO, NULL, NULL )
1090 :
1091 :
1092 : /************************************
1093 : * *
1094 : * Asymmetric Cipher Functions *
1095 : * *
1096 : ************************************/
1097 :
1098 : /* The algorithms and their IDs we support. */
1099 : enum gcry_pk_algos
1100 : {
1101 : GCRY_PK_RSA = 1, /* RSA */
1102 : GCRY_PK_RSA_E = 2, /* (deprecated: use 1). */
1103 : GCRY_PK_RSA_S = 3, /* (deprecated: use 1). */
1104 : GCRY_PK_ELG_E = 16, /* (deprecated: use 20). */
1105 : GCRY_PK_DSA = 17, /* Digital Signature Algorithm. */
1106 : GCRY_PK_ECC = 18, /* Generic ECC. */
1107 : GCRY_PK_ELG = 20, /* Elgamal */
1108 : GCRY_PK_ECDSA = 301, /* (only for external use). */
1109 : GCRY_PK_ECDH = 302, /* (only for external use). */
1110 : GCRY_PK_EDDSA = 303 /* (only for external use). */
1111 : };
1112 :
1113 : /* Flags describing usage capabilities of a PK algorithm. */
1114 : #define GCRY_PK_USAGE_SIGN 1 /* Good for signatures. */
1115 : #define GCRY_PK_USAGE_ENCR 2 /* Good for encryption. */
1116 : #define GCRY_PK_USAGE_CERT 4 /* Good to certify other keys. */
1117 : #define GCRY_PK_USAGE_AUTH 8 /* Good for authentication. */
1118 : #define GCRY_PK_USAGE_UNKN 128 /* Unknown usage flag. */
1119 :
1120 : /* Modes used with gcry_pubkey_get_sexp. */
1121 : #define GCRY_PK_GET_PUBKEY 1
1122 : #define GCRY_PK_GET_SECKEY 2
1123 :
1124 : /* Encrypt the DATA using the public key PKEY and store the result as
1125 : a newly created S-expression at RESULT. */
1126 : gcry_error_t gcry_pk_encrypt (gcry_sexp_t *result,
1127 : gcry_sexp_t data, gcry_sexp_t pkey);
1128 :
1129 : /* Decrypt the DATA using the private key SKEY and store the result as
1130 : a newly created S-expression at RESULT. */
1131 : gcry_error_t gcry_pk_decrypt (gcry_sexp_t *result,
1132 : gcry_sexp_t data, gcry_sexp_t skey);
1133 :
1134 : /* Sign the DATA using the private key SKEY and store the result as
1135 : a newly created S-expression at RESULT. */
1136 : gcry_error_t gcry_pk_sign (gcry_sexp_t *result,
1137 : gcry_sexp_t data, gcry_sexp_t skey);
1138 :
1139 : /* Check the signature SIGVAL on DATA using the public key PKEY. */
1140 : gcry_error_t gcry_pk_verify (gcry_sexp_t sigval,
1141 : gcry_sexp_t data, gcry_sexp_t pkey);
1142 :
1143 : /* Check that private KEY is sane. */
1144 : gcry_error_t gcry_pk_testkey (gcry_sexp_t key);
1145 :
1146 : /* Generate a new key pair according to the parameters given in
1147 : S_PARMS. The new key pair is returned in as an S-expression in
1148 : R_KEY. */
1149 : gcry_error_t gcry_pk_genkey (gcry_sexp_t *r_key, gcry_sexp_t s_parms);
1150 :
1151 : /* Catch all function for miscellaneous operations. */
1152 : gcry_error_t gcry_pk_ctl (int cmd, void *buffer, size_t buflen);
1153 :
1154 : /* Retrieve information about the public key algorithm ALGO. */
1155 : gcry_error_t gcry_pk_algo_info (int algo, int what,
1156 : void *buffer, size_t *nbytes);
1157 :
1158 : /* Map the public key algorithm whose ID is contained in ALGORITHM to
1159 : a string representation of the algorithm name. For unknown
1160 : algorithm IDs this functions returns "?". */
1161 : const char *gcry_pk_algo_name (int algorithm) _GCRY_GCC_ATTR_PURE;
1162 :
1163 : /* Map the algorithm NAME to a public key algorithm Id. Return 0 if
1164 : the algorithm name is not known. */
1165 : int gcry_pk_map_name (const char* name) _GCRY_GCC_ATTR_PURE;
1166 :
1167 : /* Return what is commonly referred as the key length for the given
1168 : public or private KEY. */
1169 : unsigned int gcry_pk_get_nbits (gcry_sexp_t key) _GCRY_GCC_ATTR_PURE;
1170 :
1171 : /* Return the so called KEYGRIP which is the SHA-1 hash of the public
1172 : key parameters expressed in a way depending on the algorithm. */
1173 : unsigned char *gcry_pk_get_keygrip (gcry_sexp_t key, unsigned char *array);
1174 :
1175 : /* Return the name of the curve matching KEY. */
1176 : const char *gcry_pk_get_curve (gcry_sexp_t key, int iterator,
1177 : unsigned int *r_nbits);
1178 :
1179 : /* Return an S-expression with the parameters of the named ECC curve
1180 : NAME. ALGO must be set to an ECC algorithm. */
1181 : gcry_sexp_t gcry_pk_get_param (int algo, const char *name);
1182 :
1183 : /* Return 0 if the public key algorithm A is available for use. */
1184 : #define gcry_pk_test_algo(a) \
1185 : gcry_pk_algo_info( (a), GCRYCTL_TEST_ALGO, NULL, NULL )
1186 :
1187 : /* Return an S-expression representing the context CTX. */
1188 : gcry_error_t gcry_pubkey_get_sexp (gcry_sexp_t *r_sexp,
1189 : int mode, gcry_ctx_t ctx);
1190 :
1191 :
1192 :
1193 : /************************************
1194 : * *
1195 : * Cryptograhic Hash Functions *
1196 : * *
1197 : ************************************/
1198 :
1199 : /* Algorithm IDs for the hash functions we know about. Not all of them
1200 : are implemented. */
1201 : enum gcry_md_algos
1202 : {
1203 : GCRY_MD_NONE = 0,
1204 : GCRY_MD_MD5 = 1,
1205 : GCRY_MD_SHA1 = 2,
1206 : GCRY_MD_RMD160 = 3,
1207 : GCRY_MD_MD2 = 5,
1208 : GCRY_MD_TIGER = 6, /* TIGER/192 as used by gpg <= 1.3.2. */
1209 : GCRY_MD_HAVAL = 7, /* HAVAL, 5 pass, 160 bit. */
1210 : GCRY_MD_SHA256 = 8,
1211 : GCRY_MD_SHA384 = 9,
1212 : GCRY_MD_SHA512 = 10,
1213 : GCRY_MD_SHA224 = 11,
1214 :
1215 : GCRY_MD_MD4 = 301,
1216 : GCRY_MD_CRC32 = 302,
1217 : GCRY_MD_CRC32_RFC1510 = 303,
1218 : GCRY_MD_CRC24_RFC2440 = 304,
1219 : GCRY_MD_WHIRLPOOL = 305,
1220 : GCRY_MD_TIGER1 = 306, /* TIGER fixed. */
1221 : GCRY_MD_TIGER2 = 307, /* TIGER2 variant. */
1222 : GCRY_MD_GOSTR3411_94 = 308, /* GOST R 34.11-94. */
1223 : GCRY_MD_STRIBOG256 = 309, /* GOST R 34.11-2012, 256 bit. */
1224 : GCRY_MD_STRIBOG512 = 310, /* GOST R 34.11-2012, 512 bit. */
1225 : GCRY_MD_GOSTR3411_CP = 311, /* GOST R 34.11-94 with CryptoPro-A S-Box. */
1226 : GCRY_MD_SHA3_224 = 312,
1227 : GCRY_MD_SHA3_256 = 313,
1228 : GCRY_MD_SHA3_384 = 314,
1229 : GCRY_MD_SHA3_512 = 315,
1230 : GCRY_MD_SHAKE128 = 316,
1231 : GCRY_MD_SHAKE256 = 317,
1232 : GCRY_MD_BLAKE2B_512 = 318,
1233 : GCRY_MD_BLAKE2B_384 = 319,
1234 : GCRY_MD_BLAKE2B_256 = 320,
1235 : GCRY_MD_BLAKE2B_160 = 321,
1236 : GCRY_MD_BLAKE2S_256 = 322,
1237 : GCRY_MD_BLAKE2S_224 = 323,
1238 : GCRY_MD_BLAKE2S_160 = 324,
1239 : GCRY_MD_BLAKE2S_128 = 325
1240 : };
1241 :
1242 : /* Flags used with the open function. */
1243 : enum gcry_md_flags
1244 : {
1245 : GCRY_MD_FLAG_SECURE = 1, /* Allocate all buffers in "secure" memory. */
1246 : GCRY_MD_FLAG_HMAC = 2, /* Make an HMAC out of this algorithm. */
1247 : GCRY_MD_FLAG_BUGEMU1 = 0x0100
1248 : };
1249 :
1250 : /* (Forward declaration.) */
1251 : struct gcry_md_context;
1252 :
1253 : /* This object is used to hold a handle to a message digest object.
1254 : This structure is private - only to be used by the public gcry_md_*
1255 : macros. */
1256 : typedef struct gcry_md_handle
1257 : {
1258 : /* Actual context. */
1259 : struct gcry_md_context *ctx;
1260 :
1261 : /* Buffer management. */
1262 : int bufpos;
1263 : int bufsize;
1264 : unsigned char buf[1];
1265 : } *gcry_md_hd_t;
1266 :
1267 : /* Compatibility types, do not use them. */
1268 : #ifndef GCRYPT_NO_DEPRECATED
1269 : typedef struct gcry_md_handle *GCRY_MD_HD _GCRY_GCC_ATTR_DEPRECATED;
1270 : typedef struct gcry_md_handle *GcryMDHd _GCRY_GCC_ATTR_DEPRECATED;
1271 : #endif
1272 :
1273 : /* Create a message digest object for algorithm ALGO. FLAGS may be
1274 : given as an bitwise OR of the gcry_md_flags values. ALGO may be
1275 : given as 0 if the algorithms to be used are later set using
1276 : gcry_md_enable. */
1277 : gcry_error_t gcry_md_open (gcry_md_hd_t *h, int algo, unsigned int flags);
1278 :
1279 : /* Release the message digest object HD. */
1280 : void gcry_md_close (gcry_md_hd_t hd);
1281 :
1282 : /* Add the message digest algorithm ALGO to the digest object HD. */
1283 : gcry_error_t gcry_md_enable (gcry_md_hd_t hd, int algo);
1284 :
1285 : /* Create a new digest object as an exact copy of the object HD. */
1286 : gcry_error_t gcry_md_copy (gcry_md_hd_t *bhd, gcry_md_hd_t ahd);
1287 :
1288 : /* Reset the digest object HD to its initial state. */
1289 : void gcry_md_reset (gcry_md_hd_t hd);
1290 :
1291 : /* Perform various operations on the digest object HD. */
1292 : gcry_error_t gcry_md_ctl (gcry_md_hd_t hd, int cmd,
1293 : void *buffer, size_t buflen);
1294 :
1295 : /* Pass LENGTH bytes of data in BUFFER to the digest object HD so that
1296 : it can update the digest values. This is the actual hash
1297 : function. */
1298 : void gcry_md_write (gcry_md_hd_t hd, const void *buffer, size_t length);
1299 :
1300 : /* Read out the final digest from HD return the digest value for
1301 : algorithm ALGO. */
1302 : unsigned char *gcry_md_read (gcry_md_hd_t hd, int algo);
1303 :
1304 : /* Read more output from algorithm ALGO to BUFFER of size LENGTH from
1305 : * digest object HD. Algorithm needs to be 'expendable-output function'. */
1306 : gpg_error_t gcry_md_extract (gcry_md_hd_t hd, int algo, void *buffer,
1307 : size_t length);
1308 :
1309 : /* Convenience function to calculate the hash from the data in BUFFER
1310 : of size LENGTH using the algorithm ALGO avoiding the creating of a
1311 : hash object. The hash is returned in the caller provided buffer
1312 : DIGEST which must be large enough to hold the digest of the given
1313 : algorithm. */
1314 : void gcry_md_hash_buffer (int algo, void *digest,
1315 : const void *buffer, size_t length);
1316 :
1317 : /* Convenience function to hash multiple buffers. */
1318 : gpg_error_t gcry_md_hash_buffers (int algo, unsigned int flags, void *digest,
1319 : const gcry_buffer_t *iov, int iovcnt);
1320 :
1321 : /* Retrieve the algorithm used with HD. This does not work reliable
1322 : if more than one algorithm is enabled in HD. */
1323 : int gcry_md_get_algo (gcry_md_hd_t hd);
1324 :
1325 : /* Retrieve the length in bytes of the digest yielded by algorithm
1326 : ALGO. */
1327 : unsigned int gcry_md_get_algo_dlen (int algo);
1328 :
1329 : /* Return true if the the algorithm ALGO is enabled in the digest
1330 : object A. */
1331 : int gcry_md_is_enabled (gcry_md_hd_t a, int algo);
1332 :
1333 : /* Return true if the digest object A is allocated in "secure" memory. */
1334 : int gcry_md_is_secure (gcry_md_hd_t a);
1335 :
1336 : /* Retrieve various information about the object H. */
1337 : gcry_error_t gcry_md_info (gcry_md_hd_t h, int what, void *buffer,
1338 : size_t *nbytes);
1339 :
1340 : /* Retrieve various information about the algorithm ALGO. */
1341 : gcry_error_t gcry_md_algo_info (int algo, int what, void *buffer,
1342 : size_t *nbytes);
1343 :
1344 : /* Map the digest algorithm id ALGO to a string representation of the
1345 : algorithm name. For unknown algorithms this function returns
1346 : "?". */
1347 : const char *gcry_md_algo_name (int algo) _GCRY_GCC_ATTR_PURE;
1348 :
1349 : /* Map the algorithm NAME to a digest algorithm Id. Return 0 if
1350 : the algorithm name is not known. */
1351 : int gcry_md_map_name (const char* name) _GCRY_GCC_ATTR_PURE;
1352 :
1353 : /* For use with the HMAC feature, the set MAC key to the KEY of
1354 : KEYLEN bytes. */
1355 : gcry_error_t gcry_md_setkey (gcry_md_hd_t hd, const void *key, size_t keylen);
1356 :
1357 : /* Start or stop debugging for digest handle HD; i.e. create a file
1358 : named dbgmd-<n>.<suffix> while hashing. If SUFFIX is NULL,
1359 : debugging stops and the file will be closed. */
1360 : void gcry_md_debug (gcry_md_hd_t hd, const char *suffix);
1361 :
1362 :
1363 : /* Update the hash(s) of H with the character C. This is a buffered
1364 : version of the gcry_md_write function. */
1365 : #define gcry_md_putc(h,c) \
1366 : do { \
1367 : gcry_md_hd_t h__ = (h); \
1368 : if( (h__)->bufpos == (h__)->bufsize ) \
1369 : gcry_md_write( (h__), NULL, 0 ); \
1370 : (h__)->buf[(h__)->bufpos++] = (c) & 0xff; \
1371 : } while(0)
1372 :
1373 : /* Finalize the digest calculation. This is not really needed because
1374 : gcry_md_read() does this implicitly. */
1375 : #define gcry_md_final(a) \
1376 : gcry_md_ctl ((a), GCRYCTL_FINALIZE, NULL, 0)
1377 :
1378 : /* Return 0 if the algorithm A is available for use. */
1379 : #define gcry_md_test_algo(a) \
1380 : gcry_md_algo_info( (a), GCRYCTL_TEST_ALGO, NULL, NULL )
1381 :
1382 : /* Return an DER encoded ASN.1 OID for the algorithm A in buffer B. N
1383 : must point to size_t variable with the available size of buffer B.
1384 : After return it will receive the actual size of the returned
1385 : OID. */
1386 : #define gcry_md_get_asnoid(a,b,n) \
1387 : gcry_md_algo_info((a), GCRYCTL_GET_ASNOID, (b), (n))
1388 :
1389 :
1390 :
1391 : /**********************************************
1392 : * *
1393 : * Message Authentication Code Functions *
1394 : * *
1395 : **********************************************/
1396 :
1397 : /* The data object used to hold a handle to an encryption object. */
1398 : struct gcry_mac_handle;
1399 : typedef struct gcry_mac_handle *gcry_mac_hd_t;
1400 :
1401 : /* Algorithm IDs for the hash functions we know about. Not all of them
1402 : are implemented. */
1403 : enum gcry_mac_algos
1404 : {
1405 : GCRY_MAC_NONE = 0,
1406 :
1407 : GCRY_MAC_HMAC_SHA256 = 101,
1408 : GCRY_MAC_HMAC_SHA224 = 102,
1409 : GCRY_MAC_HMAC_SHA512 = 103,
1410 : GCRY_MAC_HMAC_SHA384 = 104,
1411 : GCRY_MAC_HMAC_SHA1 = 105,
1412 : GCRY_MAC_HMAC_MD5 = 106,
1413 : GCRY_MAC_HMAC_MD4 = 107,
1414 : GCRY_MAC_HMAC_RMD160 = 108,
1415 : GCRY_MAC_HMAC_TIGER1 = 109, /* The fixed TIGER variant */
1416 : GCRY_MAC_HMAC_WHIRLPOOL = 110,
1417 : GCRY_MAC_HMAC_GOSTR3411_94 = 111,
1418 : GCRY_MAC_HMAC_STRIBOG256 = 112,
1419 : GCRY_MAC_HMAC_STRIBOG512 = 113,
1420 : GCRY_MAC_HMAC_MD2 = 114,
1421 : GCRY_MAC_HMAC_SHA3_224 = 115,
1422 : GCRY_MAC_HMAC_SHA3_256 = 116,
1423 : GCRY_MAC_HMAC_SHA3_384 = 117,
1424 : GCRY_MAC_HMAC_SHA3_512 = 118,
1425 :
1426 : GCRY_MAC_CMAC_AES = 201,
1427 : GCRY_MAC_CMAC_3DES = 202,
1428 : GCRY_MAC_CMAC_CAMELLIA = 203,
1429 : GCRY_MAC_CMAC_CAST5 = 204,
1430 : GCRY_MAC_CMAC_BLOWFISH = 205,
1431 : GCRY_MAC_CMAC_TWOFISH = 206,
1432 : GCRY_MAC_CMAC_SERPENT = 207,
1433 : GCRY_MAC_CMAC_SEED = 208,
1434 : GCRY_MAC_CMAC_RFC2268 = 209,
1435 : GCRY_MAC_CMAC_IDEA = 210,
1436 : GCRY_MAC_CMAC_GOST28147 = 211,
1437 :
1438 : GCRY_MAC_GMAC_AES = 401,
1439 : GCRY_MAC_GMAC_CAMELLIA = 402,
1440 : GCRY_MAC_GMAC_TWOFISH = 403,
1441 : GCRY_MAC_GMAC_SERPENT = 404,
1442 : GCRY_MAC_GMAC_SEED = 405,
1443 :
1444 : GCRY_MAC_POLY1305 = 501,
1445 : GCRY_MAC_POLY1305_AES = 502,
1446 : GCRY_MAC_POLY1305_CAMELLIA = 503,
1447 : GCRY_MAC_POLY1305_TWOFISH = 504,
1448 : GCRY_MAC_POLY1305_SERPENT = 505,
1449 : GCRY_MAC_POLY1305_SEED = 506
1450 : };
1451 :
1452 : /* Flags used with the open function. */
1453 : enum gcry_mac_flags
1454 : {
1455 : GCRY_MAC_FLAG_SECURE = 1 /* Allocate all buffers in "secure" memory. */
1456 : };
1457 :
1458 : /* Create a MAC handle for algorithm ALGO. FLAGS may be given as an bitwise OR
1459 : of the gcry_mac_flags values. CTX maybe NULL or gcry_ctx_t object to be
1460 : associated with HANDLE. */
1461 : gcry_error_t gcry_mac_open (gcry_mac_hd_t *handle, int algo,
1462 : unsigned int flags, gcry_ctx_t ctx);
1463 :
1464 : /* Close the MAC handle H and release all resource. */
1465 : void gcry_mac_close (gcry_mac_hd_t h);
1466 :
1467 : /* Perform various operations on the MAC object H. */
1468 : gcry_error_t gcry_mac_ctl (gcry_mac_hd_t h, int cmd, void *buffer,
1469 : size_t buflen);
1470 :
1471 : /* Retrieve various information about the MAC algorithm ALGO. */
1472 : gcry_error_t gcry_mac_algo_info (int algo, int what, void *buffer,
1473 : size_t *nbytes);
1474 :
1475 : /* Set KEY of length KEYLEN bytes for the MAC handle HD. */
1476 : gcry_error_t gcry_mac_setkey (gcry_mac_hd_t hd, const void *key,
1477 : size_t keylen);
1478 :
1479 : /* Set initialization vector IV of length IVLEN for the MAC handle HD. */
1480 : gcry_error_t gcry_mac_setiv (gcry_mac_hd_t hd, const void *iv,
1481 : size_t ivlen);
1482 :
1483 : /* Pass LENGTH bytes of data in BUFFER to the MAC object HD so that
1484 : it can update the MAC values. */
1485 : gcry_error_t gcry_mac_write (gcry_mac_hd_t hd, const void *buffer,
1486 : size_t length);
1487 :
1488 : /* Read out the final authentication code from the MAC object HD to BUFFER. */
1489 : gcry_error_t gcry_mac_read (gcry_mac_hd_t hd, void *buffer, size_t *buflen);
1490 :
1491 : /* Verify the final authentication code from the MAC object HD with BUFFER. */
1492 : gcry_error_t gcry_mac_verify (gcry_mac_hd_t hd, const void *buffer,
1493 : size_t buflen);
1494 :
1495 : /* Retrieve the algorithm used with MAC. */
1496 : int gcry_mac_get_algo (gcry_mac_hd_t hd);
1497 :
1498 : /* Retrieve the length in bytes of the MAC yielded by algorithm ALGO. */
1499 : unsigned int gcry_mac_get_algo_maclen (int algo);
1500 :
1501 : /* Retrieve the default key length in bytes used with algorithm A. */
1502 : unsigned int gcry_mac_get_algo_keylen (int algo);
1503 :
1504 : /* Map the MAC algorithm whose ID is contained in ALGORITHM to a
1505 : string representation of the algorithm name. For unknown algorithm
1506 : IDs this function returns "?". */
1507 : const char *gcry_mac_algo_name (int algorithm) _GCRY_GCC_ATTR_PURE;
1508 :
1509 : /* Map the algorithm name NAME to an MAC algorithm ID. Return 0 if
1510 : the algorithm name is not known. */
1511 : int gcry_mac_map_name (const char *name) _GCRY_GCC_ATTR_PURE;
1512 :
1513 : /* Reset the handle to the state after open/setkey. */
1514 : #define gcry_mac_reset(h) gcry_mac_ctl ((h), GCRYCTL_RESET, NULL, 0)
1515 :
1516 : /* Return 0 if the algorithm A is available for use. */
1517 : #define gcry_mac_test_algo(a) \
1518 : gcry_mac_algo_info( (a), GCRYCTL_TEST_ALGO, NULL, NULL )
1519 :
1520 :
1521 : /******************************
1522 : * *
1523 : * Key Derivation Functions *
1524 : * *
1525 : ******************************/
1526 :
1527 : /* Algorithm IDs for the KDFs. */
1528 : enum gcry_kdf_algos
1529 : {
1530 : GCRY_KDF_NONE = 0,
1531 : GCRY_KDF_SIMPLE_S2K = 16,
1532 : GCRY_KDF_SALTED_S2K = 17,
1533 : GCRY_KDF_ITERSALTED_S2K = 19,
1534 : GCRY_KDF_PBKDF1 = 33,
1535 : GCRY_KDF_PBKDF2 = 34,
1536 : GCRY_KDF_SCRYPT = 48
1537 : };
1538 :
1539 : /* Derive a key from a passphrase. */
1540 : gpg_error_t gcry_kdf_derive (const void *passphrase, size_t passphraselen,
1541 : int algo, int subalgo,
1542 : const void *salt, size_t saltlen,
1543 : unsigned long iterations,
1544 : size_t keysize, void *keybuffer);
1545 :
1546 :
1547 :
1548 :
1549 : /************************************
1550 : * *
1551 : * Random Generating Functions *
1552 : * *
1553 : ************************************/
1554 :
1555 : /* The type of the random number generator. */
1556 : enum gcry_rng_types
1557 : {
1558 : GCRY_RNG_TYPE_STANDARD = 1, /* The default CSPRNG generator. */
1559 : GCRY_RNG_TYPE_FIPS = 2, /* The FIPS X9.31 AES generator. */
1560 : GCRY_RNG_TYPE_SYSTEM = 3 /* The system's native generator. */
1561 : };
1562 :
1563 : /* The possible values for the random quality. The rule of thumb is
1564 : to use STRONG for session keys and VERY_STRONG for key material.
1565 : WEAK is usually an alias for STRONG and should not be used anymore
1566 : (except with gcry_mpi_randomize); use gcry_create_nonce instead. */
1567 : typedef enum gcry_random_level
1568 : {
1569 : GCRY_WEAK_RANDOM = 0,
1570 : GCRY_STRONG_RANDOM = 1,
1571 : GCRY_VERY_STRONG_RANDOM = 2
1572 : }
1573 : gcry_random_level_t;
1574 :
1575 : /* Fill BUFFER with LENGTH bytes of random, using random numbers of
1576 : quality LEVEL. */
1577 : void gcry_randomize (void *buffer, size_t length,
1578 : enum gcry_random_level level);
1579 :
1580 : /* Add the external random from BUFFER with LENGTH bytes into the
1581 : pool. QUALITY should either be -1 for unknown or in the range of 0
1582 : to 100 */
1583 : gcry_error_t gcry_random_add_bytes (const void *buffer, size_t length,
1584 : int quality);
1585 :
1586 : /* If random numbers are used in an application, this macro should be
1587 : called from time to time so that new stuff gets added to the
1588 : internal pool of the RNG. */
1589 : #define gcry_fast_random_poll() gcry_control (GCRYCTL_FAST_POLL, NULL)
1590 :
1591 :
1592 : /* Return NBYTES of allocated random using a random numbers of quality
1593 : LEVEL. */
1594 : void *gcry_random_bytes (size_t nbytes, enum gcry_random_level level)
1595 : _GCRY_GCC_ATTR_MALLOC;
1596 :
1597 : /* Return NBYTES of allocated random using a random numbers of quality
1598 : LEVEL. The random numbers are created returned in "secure"
1599 : memory. */
1600 : void *gcry_random_bytes_secure (size_t nbytes, enum gcry_random_level level)
1601 : _GCRY_GCC_ATTR_MALLOC;
1602 :
1603 :
1604 : /* Set the big integer W to a random value of NBITS using a random
1605 : generator with quality LEVEL. Note that by using a level of
1606 : GCRY_WEAK_RANDOM gcry_create_nonce is used internally. */
1607 : void gcry_mpi_randomize (gcry_mpi_t w,
1608 : unsigned int nbits, enum gcry_random_level level);
1609 :
1610 :
1611 : /* Create an unpredicable nonce of LENGTH bytes in BUFFER. */
1612 : void gcry_create_nonce (void *buffer, size_t length);
1613 :
1614 :
1615 :
1616 :
1617 :
1618 : /*******************************/
1619 : /* */
1620 : /* Prime Number Functions */
1621 : /* */
1622 : /*******************************/
1623 :
1624 : /* Mode values passed to a gcry_prime_check_func_t. */
1625 : #define GCRY_PRIME_CHECK_AT_FINISH 0
1626 : #define GCRY_PRIME_CHECK_AT_GOT_PRIME 1
1627 : #define GCRY_PRIME_CHECK_AT_MAYBE_PRIME 2
1628 :
1629 : /* The function should return 1 if the operation shall continue, 0 to
1630 : reject the prime candidate. */
1631 : typedef int (*gcry_prime_check_func_t) (void *arg, int mode,
1632 : gcry_mpi_t candidate);
1633 :
1634 : /* Flags for gcry_prime_generate(): */
1635 :
1636 : /* Allocate prime numbers and factors in secure memory. */
1637 : #define GCRY_PRIME_FLAG_SECRET (1 << 0)
1638 :
1639 : /* Make sure that at least one prime factor is of size
1640 : `FACTOR_BITS'. */
1641 : #define GCRY_PRIME_FLAG_SPECIAL_FACTOR (1 << 1)
1642 :
1643 : /* Generate a new prime number of PRIME_BITS bits and store it in
1644 : PRIME. If FACTOR_BITS is non-zero, one of the prime factors of
1645 : (prime - 1) / 2 must be FACTOR_BITS bits long. If FACTORS is
1646 : non-zero, allocate a new, NULL-terminated array holding the prime
1647 : factors and store it in FACTORS. FLAGS might be used to influence
1648 : the prime number generation process. */
1649 : gcry_error_t gcry_prime_generate (gcry_mpi_t *prime,
1650 : unsigned int prime_bits,
1651 : unsigned int factor_bits,
1652 : gcry_mpi_t **factors,
1653 : gcry_prime_check_func_t cb_func,
1654 : void *cb_arg,
1655 : gcry_random_level_t random_level,
1656 : unsigned int flags);
1657 :
1658 : /* Find a generator for PRIME where the factorization of (prime-1) is
1659 : in the NULL terminated array FACTORS. Return the generator as a
1660 : newly allocated MPI in R_G. If START_G is not NULL, use this as
1661 : the start for the search. */
1662 : gcry_error_t gcry_prime_group_generator (gcry_mpi_t *r_g,
1663 : gcry_mpi_t prime,
1664 : gcry_mpi_t *factors,
1665 : gcry_mpi_t start_g);
1666 :
1667 :
1668 : /* Convenience function to release the FACTORS array. */
1669 : void gcry_prime_release_factors (gcry_mpi_t *factors);
1670 :
1671 :
1672 : /* Check wether the number X is prime. */
1673 : gcry_error_t gcry_prime_check (gcry_mpi_t x, unsigned int flags);
1674 :
1675 :
1676 :
1677 : /************************************
1678 : * *
1679 : * Miscellaneous Stuff *
1680 : * *
1681 : ************************************/
1682 :
1683 : /* Release the context object CTX. */
1684 : void gcry_ctx_release (gcry_ctx_t ctx);
1685 :
1686 : /* Log data using Libgcrypt's own log interface. */
1687 : void gcry_log_debug (const char *fmt, ...) _GCRY_GCC_ATTR_PRINTF(1,2);
1688 : void gcry_log_debughex (const char *text, const void *buffer, size_t length);
1689 : void gcry_log_debugmpi (const char *text, gcry_mpi_t mpi);
1690 : void gcry_log_debugpnt (const char *text,
1691 : gcry_mpi_point_t point, gcry_ctx_t ctx);
1692 : void gcry_log_debugsxp (const char *text, gcry_sexp_t sexp);
1693 :
1694 :
1695 : /* Log levels used by the internal logging facility. */
1696 : enum gcry_log_levels
1697 : {
1698 : GCRY_LOG_CONT = 0, /* (Continue the last log line.) */
1699 : GCRY_LOG_INFO = 10,
1700 : GCRY_LOG_WARN = 20,
1701 : GCRY_LOG_ERROR = 30,
1702 : GCRY_LOG_FATAL = 40,
1703 : GCRY_LOG_BUG = 50,
1704 : GCRY_LOG_DEBUG = 100
1705 : };
1706 :
1707 : /* Type for progress handlers. */
1708 : typedef void (*gcry_handler_progress_t) (void *, const char *, int, int, int);
1709 :
1710 : /* Type for memory allocation handlers. */
1711 : typedef void *(*gcry_handler_alloc_t) (size_t n);
1712 :
1713 : /* Type for secure memory check handlers. */
1714 : typedef int (*gcry_handler_secure_check_t) (const void *);
1715 :
1716 : /* Type for memory reallocation handlers. */
1717 : typedef void *(*gcry_handler_realloc_t) (void *p, size_t n);
1718 :
1719 : /* Type for memory free handlers. */
1720 : typedef void (*gcry_handler_free_t) (void *);
1721 :
1722 : /* Type for out-of-memory handlers. */
1723 : typedef int (*gcry_handler_no_mem_t) (void *, size_t, unsigned int);
1724 :
1725 : /* Type for fatal error handlers. */
1726 : typedef void (*gcry_handler_error_t) (void *, int, const char *);
1727 :
1728 : /* Type for logging handlers. */
1729 : typedef void (*gcry_handler_log_t) (void *, int, const char *, va_list);
1730 :
1731 : /* Certain operations can provide progress information. This function
1732 : is used to register a handler for retrieving these information. */
1733 : void gcry_set_progress_handler (gcry_handler_progress_t cb, void *cb_data);
1734 :
1735 :
1736 : /* Register a custom memory allocation functions. */
1737 : void gcry_set_allocation_handler (
1738 : gcry_handler_alloc_t func_alloc,
1739 : gcry_handler_alloc_t func_alloc_secure,
1740 : gcry_handler_secure_check_t func_secure_check,
1741 : gcry_handler_realloc_t func_realloc,
1742 : gcry_handler_free_t func_free);
1743 :
1744 : /* Register a function used instead of the internal out of memory
1745 : handler. */
1746 : void gcry_set_outofcore_handler (gcry_handler_no_mem_t h, void *opaque);
1747 :
1748 : /* Register a function used instead of the internal fatal error
1749 : handler. */
1750 : void gcry_set_fatalerror_handler (gcry_handler_error_t fnc, void *opaque);
1751 :
1752 : /* Register a function used instead of the internal logging
1753 : facility. */
1754 : void gcry_set_log_handler (gcry_handler_log_t f, void *opaque);
1755 :
1756 : /* Reserved for future use. */
1757 : void gcry_set_gettext_handler (const char *(*f)(const char*));
1758 :
1759 : /* Libgcrypt uses its own memory allocation. It is important to use
1760 : gcry_free () to release memory allocated by libgcrypt. */
1761 : void *gcry_malloc (size_t n) _GCRY_GCC_ATTR_MALLOC;
1762 : void *gcry_calloc (size_t n, size_t m) _GCRY_GCC_ATTR_MALLOC;
1763 : void *gcry_malloc_secure (size_t n) _GCRY_GCC_ATTR_MALLOC;
1764 : void *gcry_calloc_secure (size_t n, size_t m) _GCRY_GCC_ATTR_MALLOC;
1765 : void *gcry_realloc (void *a, size_t n);
1766 : char *gcry_strdup (const char *string) _GCRY_GCC_ATTR_MALLOC;
1767 : void *gcry_xmalloc (size_t n) _GCRY_GCC_ATTR_MALLOC;
1768 : void *gcry_xcalloc (size_t n, size_t m) _GCRY_GCC_ATTR_MALLOC;
1769 : void *gcry_xmalloc_secure (size_t n) _GCRY_GCC_ATTR_MALLOC;
1770 : void *gcry_xcalloc_secure (size_t n, size_t m) _GCRY_GCC_ATTR_MALLOC;
1771 : void *gcry_xrealloc (void *a, size_t n);
1772 : char *gcry_xstrdup (const char * a) _GCRY_GCC_ATTR_MALLOC;
1773 : void gcry_free (void *a);
1774 :
1775 : /* Return true if A is allocated in "secure" memory. */
1776 : int gcry_is_secure (const void *a) _GCRY_GCC_ATTR_PURE;
1777 :
1778 : /* Return true if Libgcrypt is in FIPS mode. */
1779 : #define gcry_fips_mode_active() !!gcry_control (GCRYCTL_FIPS_MODE_P, 0)
1780 :
1781 :
1782 : #if 0 /* (Keep Emacsens' auto-indent happy.) */
1783 : {
1784 : #endif
1785 : #ifdef __cplusplus
1786 : }
1787 : #endif
1788 : #endif /* _GCRYPT_H */
1789 : /*
1790 : Local Variables:
1791 : buffer-read-only: t
1792 : End:
1793 : */
|
