4f4f9735b14299d7689997c0ec5348220a4bc595
[libgcrypt.git] / doc / gcrypt.texi
1 \input texinfo                  @c -*- Texinfo -*-
2 @c %**start of header
3 @setfilename gcrypt.info
4 @include version.texi
5 @settitle The Libgcrypt Reference Manual
6 @c Unify some of the indices.
7 @syncodeindex tp fn
8 @syncodeindex pg fn
9 @c %**end of header
10 @copying
11 This manual is for Libgcrypt
12 (version @value{VERSION}, @value{UPDATED}),
13 which is GNU's library of cryptographic building blocks.
14
15 @noindent
16 Copyright @copyright{} 2000, 2002, 2003, 2004, 2006, 2007, 2008, 2009, 2011, 2012 Free Software Foundation, Inc. @*
17 Copyright @copyright{} 2012, 2013, 2016, 2017 g10 Code GmbH
18
19 @quotation
20 Permission is granted to copy, distribute and/or modify this document
21 under the terms of the GNU General Public License as published by the
22 Free Software Foundation; either version 2 of the License, or (at your
23 option) any later version. The text of the license can be found in the
24 section entitled ``GNU General Public License''.
25 @end quotation
26 @end copying
27
28 @dircategory GNU Libraries
29 @direntry
30 * libgcrypt: (gcrypt).  Cryptographic function library.
31 @end direntry
32
33 @c A couple of macros with no effect on texinfo
34 @c but used by the yat2m processor.
35 @macro manpage {a}
36 @end macro
37 @macro mansect {a}
38 @end macro
39 @macro manpause
40 @end macro
41 @macro mancont
42 @end macro
43
44 @c
45 @c Printing stuff taken from gcc.
46 @c
47 @macro gnupgtabopt{body}
48 @code{\body\}
49 @end macro
50
51
52 @c
53 @c Titlepage
54 @c
55 @setchapternewpage odd
56 @titlepage
57 @title The Libgcrypt Reference Manual
58 @subtitle Version @value{VERSION}
59 @subtitle @value{UPDATED}
60 @author Werner Koch (@email{wk@@gnupg.org})
61 @author Moritz Schulte (@email{mo@@g10code.com})
62
63 @page
64 @vskip 0pt plus 1filll
65 @insertcopying
66 @end titlepage
67
68 @ifnothtml
69 @summarycontents
70 @contents
71 @page
72 @end ifnothtml
73
74
75 @ifnottex
76 @node Top
77 @top The Libgcrypt Library
78 @insertcopying
79 @end ifnottex
80
81
82 @menu
83 * Introduction::                 What is Libgcrypt.
84 * Preparation::                  What you should do before using the library.
85 * Generalities::                 General library functions and data types.
86 * Handler Functions::            Working with handler functions.
87 * Symmetric cryptography::       How to use symmetric cryptography.
88 * Public Key cryptography::      How to use public key cryptography.
89 * Hashing::                      How to use hash algorithms.
90 * Message Authentication Codes:: How to use MAC algorithms.
91 * Key Derivation::               How to derive keys from strings
92 * Random Numbers::               How to work with random numbers.
93 * S-expressions::                How to manage S-expressions.
94 * MPI library::                  How to work with multi-precision-integers.
95 * Prime numbers::                How to use the Prime number related functions.
96 * Utilities::                    Utility functions.
97 * Tools::                        Utility tools.
98 * Configuration::                Configuration files and environment variables.
99 * Architecture::                 How Libgcrypt works internally.
100
101 Appendices
102
103 * Self-Tests::                  Description of the self-tests.
104 * FIPS Mode::                   Description of the FIPS mode.
105 * Library Copying::             The GNU Lesser General Public License
106                                 says how you can copy and share Libgcrypt.
107 * Copying::                     The GNU General Public License says how you
108                                 can copy and share some parts of Libgcrypt.
109
110 Indices
111
112 * Figures and Tables::          Index of figures and tables.
113 * Concept Index::               Index of concepts and programs.
114 * Function and Data Index::     Index of functions, variables and data types.
115
116 @end menu
117
118 @ifhtml
119 @page
120 @summarycontents
121 @contents
122 @end ifhtml
123
124
125 @c **********************************************************
126 @c *******************  Introduction  ***********************
127 @c **********************************************************
128 @node Introduction
129 @chapter Introduction
130
131 Libgcrypt is a library providing cryptographic building blocks.
132
133 @menu
134 * Getting Started::             How to use this manual.
135 * Features::                    A glance at Libgcrypt's features.
136 * Overview::                    Overview about the library.
137 @end menu
138
139 @node Getting Started
140 @section Getting Started
141
142 This manual documents the Libgcrypt library application programming
143 interface (API).  All functions and data types provided by the library
144 are explained.
145
146 @noindent
147 The reader is assumed to possess basic knowledge about applied
148 cryptography.
149
150 This manual can be used in several ways.  If read from the beginning
151 to the end, it gives a good introduction into the library and how it
152 can be used in an application.  Forward references are included where
153 necessary.  Later on, the manual can be used as a reference manual to
154 get just the information needed about any particular interface of the
155 library.  Experienced programmers might want to start looking at the
156 examples at the end of the manual, and then only read up those parts
157 of the interface which are unclear.
158
159
160 @node Features
161 @section Features
162
163 Libgcrypt might have a couple of advantages over other libraries doing
164 a similar job.
165
166 @table @asis
167 @item It's Free Software
168 Anybody can use, modify, and redistribute it under the terms of the GNU
169 Lesser General Public License (@pxref{Library Copying}).  Note, that
170 some parts (which are in general not needed by applications) are subject
171 to the terms of the GNU General Public License (@pxref{Copying}); please
172 see the README file of the distribution for of list of these parts.
173
174 @item It encapsulates the low level cryptography
175 Libgcrypt provides a high level interface to cryptographic
176 building blocks using an extensible and flexible API.
177
178 @end table
179
180 @node Overview
181 @section Overview
182
183 @noindent
184 The Libgcrypt library is fully thread-safe, where it makes
185 sense to be thread-safe.  Not thread-safe are some cryptographic
186 functions that modify a certain context stored in handles.  If the
187 user really intents to use such functions from different threads on
188 the same handle, he has to take care of the serialization of such
189 functions himself.  If not described otherwise, every function is
190 thread-safe.
191
192 Libgcrypt depends on the library `libgpg-error', which contains some
193 common code used by other GnuPG components.
194
195 @c **********************************************************
196 @c *******************  Preparation  ************************
197 @c **********************************************************
198 @node Preparation
199 @chapter Preparation
200
201 To use Libgcrypt, you have to perform some changes to your
202 sources and the build system.  The necessary changes are small and
203 explained in the following sections.  At the end of this chapter, it
204 is described how the library is initialized, and how the requirements
205 of the library are verified.
206
207 @menu
208 * Header::                      What header file you need to include.
209 * Building sources::            How to build sources using the library.
210 * Building sources using Automake::  How to build sources with the help of Automake.
211 * Initializing the library::    How to initialize the library.
212 * Multi-Threading::             How Libgcrypt can be used in a MT environment.
213 * Enabling FIPS mode::          How to enable the FIPS mode.
214 * Hardware features::           How to disable hardware features.
215 @end menu
216
217
218 @node Header
219 @section Header
220
221 All interfaces (data types and functions) of the library are defined
222 in the header file @file{gcrypt.h}.  You must include this in all source
223 files using the library, either directly or through some other header
224 file, like this:
225
226 @example
227 #include <gcrypt.h>
228 @end example
229
230 The name space of Libgcrypt is @code{gcry_*} for function
231 and type names and @code{GCRY*} for other symbols.  In addition the
232 same name prefixes with one prepended underscore are reserved for
233 internal use and should never be used by an application.  Note that
234 Libgcrypt uses libgpg-error, which uses @code{gpg_*} as
235 name space for function and type names and @code{GPG_*} for other
236 symbols, including all the error codes.
237
238 @noindent
239 Certain parts of gcrypt.h may be excluded by defining these macros:
240
241 @table @code
242 @item GCRYPT_NO_MPI_MACROS
243 Do not define the shorthand macros @code{mpi_*} for @code{gcry_mpi_*}.
244
245 @item GCRYPT_NO_DEPRECATED
246 Do not include definitions for deprecated features.  This is useful to
247 make sure that no deprecated features are used.
248 @end table
249
250 @node Building sources
251 @section Building sources
252
253 If you want to compile a source file including the `gcrypt.h' header
254 file, you must make sure that the compiler can find it in the
255 directory hierarchy.  This is accomplished by adding the path to the
256 directory in which the header file is located to the compilers include
257 file search path (via the @option{-I} option).
258
259 However, the path to the include file is determined at the time the
260 source is configured.  To solve this problem, Libgcrypt ships with a small
261 helper program @command{libgcrypt-config} that knows the path to the
262 include file and other configuration options.  The options that need
263 to be added to the compiler invocation at compile time are output by
264 the @option{--cflags} option to @command{libgcrypt-config}.  The following
265 example shows how it can be used at the command line:
266
267 @example
268 gcc -c foo.c `libgcrypt-config --cflags`
269 @end example
270
271 Adding the output of @samp{libgcrypt-config --cflags} to the
272 compiler’s command line will ensure that the compiler can find the
273 Libgcrypt header file.
274
275 A similar problem occurs when linking the program with the library.
276 Again, the compiler has to find the library files.  For this to work,
277 the path to the library files has to be added to the library search path
278 (via the @option{-L} option).  For this, the option @option{--libs} to
279 @command{libgcrypt-config} can be used.  For convenience, this option
280 also outputs all other options that are required to link the program
281 with the Libgcrypt libraries (in particular, the @samp{-lgcrypt}
282 option).  The example shows how to link @file{foo.o} with the Libgcrypt
283 library to a program @command{foo}.
284
285 @example
286 gcc -o foo foo.o `libgcrypt-config --libs`
287 @end example
288
289 Of course you can also combine both examples to a single command by
290 specifying both options to @command{libgcrypt-config}:
291
292 @example
293 gcc -o foo foo.c `libgcrypt-config --cflags --libs`
294 @end example
295
296 @node Building sources using Automake
297 @section Building sources using Automake
298
299 It is much easier if you use GNU Automake instead of writing your own
300 Makefiles.  If you do that, you do not have to worry about finding and
301 invoking the @command{libgcrypt-config} script at all.
302 Libgcrypt provides an extension to Automake that does all
303 the work for you.
304
305 @c A simple macro for optional variables.
306 @macro ovar{varname}
307 @r{[}@var{\varname\}@r{]}
308 @end macro
309 @defmac AM_PATH_LIBGCRYPT (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found})
310 Check whether Libgcrypt (at least version
311 @var{minimum-version}, if given) exists on the host system.  If it is
312 found, execute @var{action-if-found}, otherwise do
313 @var{action-if-not-found}, if given.
314
315 Additionally, the function defines @code{LIBGCRYPT_CFLAGS} to the
316 flags needed for compilation of the program to find the
317 @file{gcrypt.h} header file, and @code{LIBGCRYPT_LIBS} to the linker
318 flags needed to link the program to the Libgcrypt library.  If the
319 used helper script does not match the target type you are building for
320 a warning is printed and the string @code{libgcrypt} is appended to the
321 variable @code{gpg_config_script_warn}.
322
323 This macro searches for @command{libgcrypt-config} along the PATH.  If
324 you are cross-compiling, it is useful to set the environment variable
325 @code{SYSROOT} to the top directory of your target.  The macro will
326 then first look for the helper program in the @file{bin} directory
327 below that top directory.  An absolute directory name must be used for
328 @code{SYSROOT}.  Finally, if the configure command line option
329 @code{--with-libgcrypt-prefix} is used, only its value is used for the top
330 directory below which the helper script is expected.
331
332 @end defmac
333
334 You can use the defined Autoconf variables like this in your
335 @file{Makefile.am}:
336
337 @example
338 AM_CPPFLAGS = $(LIBGCRYPT_CFLAGS)
339 LDADD = $(LIBGCRYPT_LIBS)
340 @end example
341
342 @node Initializing the library
343 @section Initializing the library
344
345 Before the library can be used, it must initialize itself.  This is
346 achieved by invoking the function @code{gcry_check_version} described
347 below.
348
349 Also, it is often desirable to check that the version of
350 Libgcrypt used is indeed one which fits all requirements.
351 Even with binary compatibility, new features may have been introduced,
352 but due to problem with the dynamic linker an old version may actually
353 be used.  So you may want to check that the version is okay right
354 after program startup.
355
356 @deftypefun {const char *} gcry_check_version (const char *@var{req_version})
357
358 The function @code{gcry_check_version} initializes some subsystems used
359 by Libgcrypt and must be invoked before any other function in the
360 library.
361 @xref{Multi-Threading}.
362
363 Furthermore, this function returns the version number of the library.
364 It can also verify that the version number is higher than a certain
365 required version number @var{req_version}, if this value is not a null
366 pointer.
367 @end deftypefun
368
369 Libgcrypt uses a concept known as secure memory, which is a region of
370 memory set aside for storing sensitive data.  Because such memory is a
371 scarce resource, it needs to be setup in advanced to a fixed size.
372 Further, most operating systems have special requirements on how that
373 secure memory can be used.  For example, it might be required to install
374 an application as ``setuid(root)'' to allow allocating such memory.
375 Libgcrypt requires a sequence of initialization steps to make sure that
376 this works correctly.  The following examples show the necessary steps.
377
378 If you don't have a need for secure memory, for example if your
379 application does not use secret keys or other confidential data or it
380 runs in a controlled environment where key material floating around in
381 memory is not a problem, you should initialize Libgcrypt this way:
382
383 @example
384   /* Version check should be the very first call because it
385      makes sure that important subsystems are initialized. */
386   if (!gcry_check_version (GCRYPT_VERSION))
387     @{
388       fputs ("libgcrypt version mismatch\n", stderr);
389       exit (2);
390     @}
391
392   /* Disable secure memory.  */
393   gcry_control (GCRYCTL_DISABLE_SECMEM, 0);
394
395   /* ... If required, other initialization goes here.  */
396
397   /* Tell Libgcrypt that initialization has completed. */
398   gcry_control (GCRYCTL_INITIALIZATION_FINISHED, 0);
399 @end example
400
401
402 If you have to protect your keys or other information in memory against
403 being swapped out to disk and to enable an automatic overwrite of used
404 and freed memory, you need to initialize Libgcrypt this way:
405
406 @example
407   /* Version check should be the very first call because it
408      makes sure that important subsystems are initialized. */
409   if (!gcry_check_version (GCRYPT_VERSION))
410     @{
411       fputs ("libgcrypt version mismatch\n", stderr);
412       exit (2);
413     @}
414
415 @anchor{sample-use-suspend-secmem}
416   /* We don't want to see any warnings, e.g. because we have not yet
417      parsed program options which might be used to suppress such
418      warnings. */
419   gcry_control (GCRYCTL_SUSPEND_SECMEM_WARN);
420
421   /* ... If required, other initialization goes here.  Note that the
422      process might still be running with increased privileges and that
423      the secure memory has not been initialized.  */
424
425   /* Allocate a pool of 16k secure memory.  This makes the secure memory
426      available and also drops privileges where needed.  Note that by
427      using functions like gcry_xmalloc_secure and gcry_mpi_snew Libgcrypt
428      may expand the secure memory pool with memory which lacks the
429      property of not being swapped out to disk.   */
430   gcry_control (GCRYCTL_INIT_SECMEM, 16384, 0);
431
432 @anchor{sample-use-resume-secmem}
433   /* It is now okay to let Libgcrypt complain when there was/is
434      a problem with the secure memory. */
435   gcry_control (GCRYCTL_RESUME_SECMEM_WARN);
436
437   /* ... If required, other initialization goes here.  */
438
439   /* Tell Libgcrypt that initialization has completed. */
440   gcry_control (GCRYCTL_INITIALIZATION_FINISHED, 0);
441 @end example
442
443 It is important that these initialization steps are not done by a
444 library but by the actual application.  A library using Libgcrypt might
445 want to check for finished initialization using:
446
447 @example
448   if (!gcry_control (GCRYCTL_INITIALIZATION_FINISHED_P))
449     @{
450       fputs ("libgcrypt has not been initialized\n", stderr);
451       abort ();
452     @}
453 @end example
454
455 Instead of terminating the process, the library may instead print a
456 warning and try to initialize Libgcrypt itself.  See also the section on
457 multi-threading below for more pitfalls.
458
459
460
461 @node Multi-Threading
462 @section Multi-Threading
463
464 As mentioned earlier, the Libgcrypt library is
465 thread-safe if you adhere to the following requirements:
466
467 @itemize @bullet
468 @item
469 If you use pthread and your applications forks and does not directly
470 call exec (even calling stdio functions), all kind of problems may
471 occur.  Future versions of Libgcrypt will try to cleanup using
472 pthread_atfork but even that may lead to problems.  This is a common
473 problem with almost all applications using pthread and fork.
474
475
476 @item
477 The function @code{gcry_check_version} must be called before any other
478 function in the library.  To
479 achieve this in multi-threaded programs, you must synchronize the
480 memory with respect to other threads that also want to use
481 Libgcrypt.  For this, it is sufficient to call
482 @code{gcry_check_version} before creating the other threads using
483 Libgcrypt@footnote{At least this is true for POSIX threads,
484 as @code{pthread_create} is a function that synchronizes memory with
485 respects to other threads.  There are many functions which have this
486 property, a complete list can be found in POSIX, IEEE Std 1003.1-2003,
487 Base Definitions, Issue 6, in the definition of the term ``Memory
488 Synchronization''.  For other thread packages, more relaxed or more
489 strict rules may apply.}.
490
491 @item
492 Just like the function @code{gpg_strerror}, the function
493 @code{gcry_strerror} is not thread safe.  You have to use
494 @code{gpg_strerror_r} instead.
495
496 @end itemize
497
498
499 @node Enabling FIPS mode
500 @section How to enable the FIPS mode
501 @cindex FIPS mode
502 @cindex FIPS 140
503
504 @anchor{enabling fips mode}
505 Libgcrypt may be used in a FIPS 140-2 mode.  Note, that this does not
506 necessary mean that Libcgrypt is an appoved FIPS 140-2 module.  Check the
507 NIST database at @url{http://csrc.nist.gov/groups/STM/cmvp/} to see what
508 versions of Libgcrypt are approved.
509
510 Because FIPS 140 has certain restrictions on the use of cryptography
511 which are not always wanted, Libgcrypt needs to be put into FIPS mode
512 explicitly.  Three alternative mechanisms are provided to switch
513 Libgcrypt into this mode:
514
515 @itemize
516 @item
517 If the file @file{/proc/sys/crypto/fips_enabled} exists and contains a
518 numeric value other than @code{0}, Libgcrypt is put into FIPS mode at
519 initialization time.  Obviously this works only on systems with a
520 @code{proc} file system (i.e. GNU/Linux).
521
522 @item
523 If the file @file{/etc/gcrypt/fips_enabled} exists, Libgcrypt is put
524 into FIPS mode at initialization time.  Note that this filename is
525 hardwired and does not depend on any configuration options.
526
527 @item
528 If the application requests FIPS mode using the control command
529 @code{GCRYCTL_FORCE_FIPS_MODE}.  This must be done prior to any
530 initialization (i.e. before @code{gcry_check_version}).
531
532 @end itemize
533
534 @cindex Enforced FIPS mode
535
536 In addition to the standard FIPS mode, Libgcrypt may also be put into
537 an Enforced FIPS mode by writing a non-zero value into the file
538 @file{/etc/gcrypt/fips_enabled} or by using the control command
539 @code{GCRYCTL_SET_ENFORCED_FIPS_FLAG} before any other calls to
540 libgcrypt.  The Enforced FIPS mode helps to detect applications
541 which don't fulfill all requirements for using
542 Libgcrypt in FIPS mode (@pxref{FIPS Mode}).
543
544 Once Libgcrypt has been put into FIPS mode, it is not possible to
545 switch back to standard mode without terminating the process first.
546 If the logging verbosity level of Libgcrypt has been set to at least
547 2, the state transitions and the self-tests are logged.
548
549 @node Hardware features
550 @section How to disable hardware features
551 @cindex hardware features
552
553 @anchor{hardware features}
554 Libgcrypt makes use of certain hardware features.  If the use of a
555 feature is not desired it may be either be disabled by a program or
556 globally using a configuration file.  The currently supported features
557 are
558
559 @table @code
560 @item padlock-rng
561 @item padlock-aes
562 @item padlock-sha
563 @item padlock-mmul
564 @item intel-cpu
565 @item intel-fast-shld
566 @item intel-bmi2
567 @item intel-ssse3
568 @item intel-pclmul
569 @item intel-aesni
570 @item intel-rdrand
571 @item intel-avx
572 @item intel-avx2
573 @item intel-rdtsc
574 @item arm-neon
575 @end table
576
577 To disable a feature for all processes using Libgcrypt 1.6 or newer,
578 create the file @file{/etc/gcrypt/hwf.deny} and put each feature not
579 to be used on a single line.  Empty lines, white space, and lines
580 prefixed with a hash mark are ignored.  The file should be world
581 readable.
582
583 To disable a feature specifically for a program that program must tell
584 it Libgcrypt before before calling @code{gcry_check_version}.
585 Example:@footnote{NB. Libgcrypt uses the RDRAND feature only as one
586 source of entropy.  A CPU with a broken RDRAND will thus not
587 compromise of the random number generator}
588
589 @example
590   gcry_control (GCRYCTL_DISABLE_HWF, "intel-rdrand", NULL);
591 @end example
592
593 @noindent
594 To print the list of active features you may use this command:
595
596 @example
597   mpicalc --print-config | grep ^hwflist: | tr : '\n' | tail -n +2
598 @end example
599
600
601 @c **********************************************************
602 @c *******************  General  ****************************
603 @c **********************************************************
604 @node Generalities
605 @chapter Generalities
606
607 @menu
608 * Controlling the library::     Controlling Libgcrypt's behavior.
609 * Error Handling::              Error codes and such.
610 @end menu
611
612 @node Controlling the library
613 @section Controlling the library
614
615 @deftypefun gcry_error_t gcry_control (enum gcry_ctl_cmds @var{cmd}, ...)
616
617 This function can be used to influence the general behavior of
618 Libgcrypt in several ways.  Depending on @var{cmd}, more
619 arguments can or have to be provided.
620
621 @table @code
622 @item GCRYCTL_ENABLE_M_GUARD; Arguments: none
623 This command enables the built-in memory guard.  It must not be used
624 to activate the memory guard after the memory management has already
625 been used; therefore it can ONLY be used before
626 @code{gcry_check_version}.  Note that the memory guard is NOT used
627 when the user of the library has set his own memory management
628 callbacks.
629
630 @item GCRYCTL_ENABLE_QUICK_RANDOM; Arguments: none
631 This command inhibits the use the very secure random quality level
632 (@code{GCRY_VERY_STRONG_RANDOM}) and degrades all request down to
633 @code{GCRY_STRONG_RANDOM}.  In general this is not recommended.  However,
634 for some applications the extra quality random Libgcrypt tries to create
635 is not justified and this option may help to get better performance.
636 Please check with a crypto expert whether this option can be used for
637 your application.
638
639 This option can only be used at initialization time.
640
641
642 @item GCRYCTL_DUMP_RANDOM_STATS; Arguments: none
643 This command dumps random number generator related statistics to the
644 library's logging stream.
645
646 @item GCRYCTL_DUMP_MEMORY_STATS; Arguments: none
647 This command dumps memory management related statistics to the library's
648 logging stream.
649
650 @item GCRYCTL_DUMP_SECMEM_STATS; Arguments: none
651 This command dumps secure memory management related statistics to the
652 library's logging stream.
653
654 @item GCRYCTL_DROP_PRIVS; Arguments: none
655 This command disables the use of secure memory and drops the privileges
656 of the current process.  This command has not much use; the suggested way
657 to disable secure memory is to use @code{GCRYCTL_DISABLE_SECMEM} right
658 after initialization.
659
660 @item GCRYCTL_DISABLE_SECMEM; Arguments: none
661 This command disables the use of secure memory.  If this command is
662 used in FIPS mode, FIPS mode will be disabled and the function
663 @code{gcry_fips_mode_active} returns false.  However, in Enforced FIPS
664 mode this command has no effect at all.
665
666 Many applications do not require secure memory, so they should disable
667 it right away.  This command should be executed right after
668 @code{gcry_check_version}.
669
670 @item GCRYCTL_DISABLE_LOCKED_SECMEM; Arguments: none
671 This command disables the use of the mlock call for secure memory.
672 Disabling the use of mlock may for example be done if an encrypted
673 swap space is in use.  This command should be executed right after
674 @code{gcry_check_version}.  Note that by using functions like
675 gcry_xmalloc_secure and gcry_mpi_snew Libgcrypt may expand the secure
676 memory pool with memory which lacks the property of not being swapped
677 out to disk (but will still be zeroed out on free).
678
679 @item GCRYCTL_DISABLE_PRIV_DROP; Arguments: none
680 This command sets a global flag to tell the secure memory subsystem
681 that it shall not drop privileges after secure memory has been
682 allocated.  This command is commonly used right after
683 @code{gcry_check_version} but may also be used right away at program
684 startup.  It won't have an effect after the secure memory pool has
685 been initialized.  WARNING: A process running setuid(root) is a severe
686 security risk.  Processes making use of Libgcrypt or other complex
687 code should drop these extra privileges as soon as possible.  If this
688 command has been used the caller is responsible for dropping the
689 privileges.
690
691 @item GCRYCTL_INIT_SECMEM; Arguments: unsigned int nbytes
692 This command is used to allocate a pool of secure memory and thus
693 enabling the use of secure memory.  It also drops all extra privileges
694 the process has (i.e. if it is run as setuid (root)).  If the argument
695 @var{nbytes} is 0, secure memory will be disabled.  The minimum amount
696 of secure memory allocated is currently 16384 bytes; you may thus use a
697 value of 1 to request that default size.
698
699 @item GCRYCTL_AUTO_EXPAND_SECMEM; Arguments: unsigned int chunksize
700 This command enables on-the-fly expanding of the secure memory area.
701 Note that by using functions like @code{gcry_xmalloc_secure} and
702 @code{gcry_mpi_snew} will do this auto expanding anyway.  The argument
703 to this option is the suggested size for new secure memory areas.  A
704 larger size improves performance of all memory allocation and
705 releasing functions.  The given chunksize is rounded up to the next
706 32KiB.  The drawback of auto expanding is that memory might be swapped
707 out to disk; this can be fixed by configuring the system to use an
708 encrypted swap space.
709
710 @item GCRYCTL_TERM_SECMEM; Arguments: none
711 This command zeroises the secure memory and destroys the handler.  The
712 secure memory pool may not be used anymore after running this command.
713 If the secure memory pool as already been destroyed, this command has
714 no effect.  Applications might want to run this command from their
715 exit handler to make sure that the secure memory gets properly
716 destroyed.  This command is not necessarily thread-safe but that
717 should not be needed in cleanup code.  It may be called from a signal
718 handler.
719
720 @item GCRYCTL_DISABLE_SECMEM_WARN; Arguments: none
721 Disable warning messages about problems with the secure memory
722 subsystem. This command should be run right after
723 @code{gcry_check_version}.
724
725 @item GCRYCTL_SUSPEND_SECMEM_WARN; Arguments: none
726 Postpone warning messages from the secure memory subsystem.
727 @xref{sample-use-suspend-secmem,,the initialization example}, on how to
728 use it.
729
730 @item GCRYCTL_RESUME_SECMEM_WARN; Arguments: none
731 Resume warning messages from the secure memory subsystem.
732 @xref{sample-use-resume-secmem,,the initialization example}, on how to
733 use it.
734
735 @item GCRYCTL_USE_SECURE_RNDPOOL; Arguments: none
736 This command tells the PRNG to store random numbers in secure memory.
737 This command should be run right after @code{gcry_check_version} and not
738 later than the command GCRYCTL_INIT_SECMEM.  Note that in FIPS mode the
739 secure memory is always used.
740
741 @item GCRYCTL_SET_RANDOM_SEED_FILE; Arguments: const char *filename
742 This command specifies the file, which is to be used as seed file for
743 the PRNG.  If the seed file is registered prior to initialization of the
744 PRNG, the seed file's content (if it exists and seems to be valid) is
745 fed into the PRNG pool.  After the seed file has been registered, the
746 PRNG can be signalled to write out the PRNG pool's content into the seed
747 file with the following command.
748
749
750 @item GCRYCTL_UPDATE_RANDOM_SEED_FILE; Arguments: none
751 Write out the PRNG pool's content into the registered seed file.
752
753 Multiple instances of the applications sharing the same random seed file
754 can be started in parallel, in which case they will read out the same
755 pool and then race for updating it (the last update overwrites earlier
756 updates).  They will differentiate only by the weak entropy that is
757 added in read_seed_file based on the PID and clock, and up to 16 bytes
758 of weak random non-blockingly.  The consequence is that the output of
759 these different instances is correlated to some extent.  In a perfect
760 attack scenario, the attacker can control (or at least guess) the PID
761 and clock of the application, and drain the system's entropy pool to
762 reduce the "up to 16 bytes" above to 0.  Then the dependencies of the
763 initial states of the pools are completely known.  Note that this is not
764 an issue if random of @code{GCRY_VERY_STRONG_RANDOM} quality is
765 requested as in this case enough extra entropy gets mixed.  It is also
766 not an issue when using Linux (rndlinux driver), because this one
767 guarantees to read full 16 bytes from /dev/urandom and thus there is no
768 way for an attacker without kernel access to control these 16 bytes.
769
770 @item GCRYCTL_CLOSE_RANDOM_DEVICE; Arguments: none
771 Try to close the random device.  If on Unix system you call fork(),
772 the child process does no call exec(), and you do not intend to use
773 Libgcrypt in the child, it might be useful to use this control code to
774 close the inherited file descriptors of the random device.  If
775 Libgcrypt is later used again by the child, the device will be
776 re-opened.  On non-Unix systems this control code is ignored.
777
778 @item GCRYCTL_SET_VERBOSITY; Arguments: int level
779 This command sets the verbosity of the logging.  A level of 0 disables
780 all extra logging whereas positive numbers enable more verbose logging.
781 The level may be changed at any time but be aware that no memory
782 synchronization is done so the effect of this command might not
783 immediately show up in other threads.  This command may even be used
784 prior to @code{gcry_check_version}.
785
786 @item GCRYCTL_SET_DEBUG_FLAGS; Arguments: unsigned int flags
787 Set the debug flag bits as given by the argument.  Be aware that that no
788 memory synchronization is done so the effect of this command might not
789 immediately show up in other threads.  The debug flags are not
790 considered part of the API and thus may change without notice.  As of
791 now bit 0 enables debugging of cipher functions and bit 1 debugging of
792 multi-precision-integers.  This command may even be used prior to
793 @code{gcry_check_version}.
794
795 @item GCRYCTL_CLEAR_DEBUG_FLAGS; Arguments: unsigned int flags
796 Set the debug flag bits as given by the argument.  Be aware that that no
797 memory synchronization is done so the effect of this command might not
798 immediately show up in other threads.  This command may even be used
799 prior to @code{gcry_check_version}.
800
801 @item GCRYCTL_DISABLE_INTERNAL_LOCKING; Arguments: none
802 This command does nothing.  It exists only for backward compatibility.
803
804 @item GCRYCTL_ANY_INITIALIZATION_P; Arguments: none
805 This command returns true if the library has been basically initialized.
806 Such a basic initialization happens implicitly with many commands to get
807 certain internal subsystems running.  The common and suggested way to
808 do this basic initialization is by calling gcry_check_version.
809
810 @item GCRYCTL_INITIALIZATION_FINISHED; Arguments: none
811 This command tells the library that the application has finished the
812 initialization.
813
814 @item GCRYCTL_INITIALIZATION_FINISHED_P; Arguments: none
815 This command returns true if the command@*
816 GCRYCTL_INITIALIZATION_FINISHED has already been run.
817
818 @item GCRYCTL_SET_THREAD_CBS; Arguments: struct ath_ops *ath_ops
819 This command is obsolete since version 1.6.
820
821 @item GCRYCTL_FAST_POLL; Arguments: none
822 Run a fast random poll.
823
824 @item GCRYCTL_SET_RNDEGD_SOCKET; Arguments: const char *filename
825 This command may be used to override the default name of the EGD socket
826 to connect to.  It may be used only during initialization as it is not
827 thread safe.  Changing the socket name again is not supported.  The
828 function may return an error if the given filename is too long for a
829 local socket name.
830
831 EGD is an alternative random gatherer, used only on systems lacking a
832 proper random device.
833
834 @item GCRYCTL_PRINT_CONFIG; Arguments: FILE *stream
835 This command dumps information pertaining to the configuration of the
836 library to the given stream.  If NULL is given for @var{stream}, the log
837 system is used.  This command may be used before the initialization has
838 been finished but not before a @code{gcry_check_version}.  Note that
839 the macro @code{estream_t} can be used instead of @code{gpgrt_stream_t}.
840
841 @item GCRYCTL_OPERATIONAL_P; Arguments: none
842 This command returns true if the library is in an operational state.
843 This information makes only sense in FIPS mode.  In contrast to other
844 functions, this is a pure test function and won't put the library into
845 FIPS mode or change the internal state.  This command may be used before
846 the initialization has been finished but not before a @code{gcry_check_version}.
847
848 @item GCRYCTL_FIPS_MODE_P; Arguments: none
849 This command returns true if the library is in FIPS mode.  Note, that
850 this is no indication about the current state of the library.  This
851 command may be used before the initialization has been finished but not
852 before a @code{gcry_check_version}.  An application may use this command or
853 the convenience macro below to check whether FIPS mode is actually
854 active.
855
856 @deftypefun int gcry_fips_mode_active (void)
857
858 Returns true if the FIPS mode is active.  Note that this is
859 implemented as a macro.
860 @end deftypefun
861
862
863
864 @item GCRYCTL_FORCE_FIPS_MODE; Arguments: none
865 Running this command puts the library into FIPS mode.  If the library is
866 already in FIPS mode, a self-test is triggered and thus the library will
867 be put into operational state.  This command may be used before a call
868 to @code{gcry_check_version} and that is actually the recommended way to let an
869 application switch the library into FIPS mode.  Note that Libgcrypt will
870 reject an attempt to switch to fips mode during or after the initialization.
871
872 @item GCRYCTL_SET_ENFORCED_FIPS_FLAG; Arguments: none
873 Running this command sets the internal flag that puts the library into
874 the enforced FIPS mode during the FIPS mode initialization.  This command
875 does not affect the library if the library is not put into the FIPS mode and
876 it must be used before any other libgcrypt library calls that initialize
877 the library such as @code{gcry_check_version}. Note that Libgcrypt will
878 reject an attempt to switch to the enforced fips mode during or after
879 the initialization.
880
881 @item GCRYCTL_SET_PREFERRED_RNG_TYPE; Arguments: int
882 These are advisory commands to select a certain random number
883 generator.  They are only advisory because libraries may not know what
884 an application actually wants or vice versa.  Thus Libgcrypt employs a
885 priority check to select the actually used RNG.  If an applications
886 selects a lower priority RNG but a library requests a higher priority
887 RNG Libgcrypt will switch to the higher priority RNG.  Applications
888 and libraries should use these control codes before
889 @code{gcry_check_version}.  The available generators are:
890 @table @code
891 @item GCRY_RNG_TYPE_STANDARD
892 A conservative standard generator based on the ``Continuously Seeded
893 Pseudo Random Number Generator'' designed by Peter Gutmann.
894 @item GCRY_RNG_TYPE_FIPS
895 A deterministic random number generator conforming to he document
896 ``NIST-Recommended Random Number Generator Based on ANSI X9.31
897 Appendix A.2.4 Using the 3-Key Triple DES and AES Algorithms''
898 (2005-01-31).  This implementation uses the AES variant.
899 @item GCRY_RNG_TYPE_SYSTEM
900 A wrapper around the system's native RNG.  On Unix system these are
901 usually the /dev/random and /dev/urandom devices.
902 @end table
903 The default is @code{GCRY_RNG_TYPE_STANDARD} unless FIPS mode as been
904 enabled; in which case @code{GCRY_RNG_TYPE_FIPS} is used and locked
905 against further changes.
906
907 @item GCRYCTL_GET_CURRENT_RNG_TYPE; Arguments: int *
908 This command stores the type of the currently used RNG as an integer
909 value at the provided address.
910
911
912 @item GCRYCTL_SELFTEST; Arguments: none
913 This may be used at anytime to have the library run all implemented
914 self-tests.  It works in standard and in FIPS mode.  Returns 0 on
915 success or an error code on failure.
916
917 @item GCRYCTL_DISABLE_HWF; Arguments: const char *name
918
919 Libgcrypt detects certain features of the CPU at startup time.  For
920 performance tests it is sometimes required not to use such a feature.
921 This option may be used to disable a certain feature; i.e. Libgcrypt
922 behaves as if this feature has not been detected.  This call can be
923 used several times to disable a set of features, or features may be
924 given as a colon or comma delimited string.  The special feature
925 "all" can be used to disable all available features.
926
927 Note that the detection code might be run if the feature has been
928 disabled.  This command must be used at initialization time;
929 i.e. before calling @code{gcry_check_version}.
930
931 @item GCRYCTL_REINIT_SYSCALL_CLAMP; Arguments: none
932
933 Libgcrypt wraps blocking system calls with two functions calls
934 (``system call clamp'') to give user land threading libraries a hook
935 for re-scheduling.  This works by reading the system call clamp from
936 Libgpg-error at initialization time.  However sometimes Libgcrypt
937 needs to be initialized before the user land threading systems and at
938 that point the system call clamp has not been registered with
939 Libgpg-error and in turn Libgcrypt would not use them.  The control
940 code can be used to tell Libgcrypt that a system call clamp has now
941 been registered with Libgpg-error and advised it to read the clamp
942 again.  Obviously this control code may only be used before a second
943 thread is started in a process.
944
945
946 @end table
947
948 @end deftypefun
949
950 @c **********************************************************
951 @c *******************  Errors  ****************************
952 @c **********************************************************
953 @node Error Handling
954 @section Error Handling
955
956 Many functions in Libgcrypt can return an error if they
957 fail.  For this reason, the application should always catch the error
958 condition and take appropriate measures, for example by releasing the
959 resources and passing the error up to the caller, or by displaying a
960 descriptive message to the user and cancelling the operation.
961
962 Some error values do not indicate a system error or an error in the
963 operation, but the result of an operation that failed properly.  For
964 example, if you try to decrypt a tempered message, the decryption will
965 fail.  Another error value actually means that the end of a data
966 buffer or list has been reached.  The following descriptions explain
967 for many error codes what they mean usually.  Some error values have
968 specific meanings if returned by a certain functions.  Such cases are
969 described in the documentation of those functions.
970
971 Libgcrypt uses the @code{libgpg-error} library.  This allows to share
972 the error codes with other components of the GnuPG system, and to pass
973 error values transparently from the crypto engine, or some helper
974 application of the crypto engine, to the user.  This way no
975 information is lost.  As a consequence, Libgcrypt does not use its own
976 identifiers for error codes, but uses those provided by
977 @code{libgpg-error}.  They usually start with @code{GPG_ERR_}.
978
979 However, Libgcrypt does provide aliases for the functions
980 defined in libgpg-error, which might be preferred for name space
981 consistency.
982
983
984 Most functions in Libgcrypt return an error code in the case
985 of failure.  For this reason, the application should always catch the
986 error condition and take appropriate measures, for example by
987 releasing the resources and passing the error up to the caller, or by
988 displaying a descriptive message to the user and canceling the
989 operation.
990
991 Some error values do not indicate a system error or an error in the
992 operation, but the result of an operation that failed properly.
993
994 GnuPG components, including Libgcrypt, use an extra library named
995 libgpg-error to provide a common error handling scheme.  For more
996 information on libgpg-error, see the according manual.
997
998 @menu
999 * Error Values::                The error value and what it means.
1000 * Error Sources::               A list of important error sources.
1001 * Error Codes::                 A list of important error codes.
1002 * Error Strings::               How to get a descriptive string from a value.
1003 @end menu
1004
1005
1006 @node Error Values
1007 @subsection Error Values
1008 @cindex error values
1009 @cindex error codes
1010 @cindex error sources
1011
1012 @deftp {Data type} {gcry_err_code_t}
1013 The @code{gcry_err_code_t} type is an alias for the
1014 @code{libgpg-error} type @code{gpg_err_code_t}.  The error code
1015 indicates the type of an error, or the reason why an operation failed.
1016
1017 A list of important error codes can be found in the next section.
1018 @end deftp
1019
1020 @deftp {Data type} {gcry_err_source_t}
1021 The @code{gcry_err_source_t} type is an alias for the
1022 @code{libgpg-error} type @code{gpg_err_source_t}.  The error source
1023 has not a precisely defined meaning.  Sometimes it is the place where
1024 the error happened, sometimes it is the place where an error was
1025 encoded into an error value.  Usually the error source will give an
1026 indication to where to look for the problem.  This is not always true,
1027 but it is attempted to achieve this goal.
1028
1029 A list of important error sources can be found in the next section.
1030 @end deftp
1031
1032 @deftp {Data type} {gcry_error_t}
1033 The @code{gcry_error_t} type is an alias for the @code{libgpg-error}
1034 type @code{gpg_error_t}.  An error value like this has always two
1035 components, an error code and an error source.  Both together form the
1036 error value.
1037
1038 Thus, the error value can not be directly compared against an error
1039 code, but the accessor functions described below must be used.
1040 However, it is guaranteed that only 0 is used to indicate success
1041 (@code{GPG_ERR_NO_ERROR}), and that in this case all other parts of
1042 the error value are set to 0, too.
1043
1044 Note that in Libgcrypt, the error source is used purely for
1045 diagnostic purposes.  Only the error code should be checked to test
1046 for a certain outcome of a function.  The manual only documents the
1047 error code part of an error value.  The error source is left
1048 unspecified and might be anything.
1049 @end deftp
1050
1051 @deftypefun {gcry_err_code_t} gcry_err_code (@w{gcry_error_t @var{err}})
1052 The static inline function @code{gcry_err_code} returns the
1053 @code{gcry_err_code_t} component of the error value @var{err}.  This
1054 function must be used to extract the error code from an error value in
1055 order to compare it with the @code{GPG_ERR_*} error code macros.
1056 @end deftypefun
1057
1058 @deftypefun {gcry_err_source_t} gcry_err_source (@w{gcry_error_t @var{err}})
1059 The static inline function @code{gcry_err_source} returns the
1060 @code{gcry_err_source_t} component of the error value @var{err}.  This
1061 function must be used to extract the error source from an error value in
1062 order to compare it with the @code{GPG_ERR_SOURCE_*} error source macros.
1063 @end deftypefun
1064
1065 @deftypefun {gcry_error_t} gcry_err_make (@w{gcry_err_source_t @var{source}}, @w{gcry_err_code_t @var{code}})
1066 The static inline function @code{gcry_err_make} returns the error
1067 value consisting of the error source @var{source} and the error code
1068 @var{code}.
1069
1070 This function can be used in callback functions to construct an error
1071 value to return it to the library.
1072 @end deftypefun
1073
1074 @deftypefun {gcry_error_t} gcry_error (@w{gcry_err_code_t @var{code}})
1075 The static inline function @code{gcry_error} returns the error value
1076 consisting of the default error source and the error code @var{code}.
1077
1078 For @acronym{GCRY} applications, the default error source is
1079 @code{GPG_ERR_SOURCE_USER_1}.  You can define
1080 @code{GCRY_ERR_SOURCE_DEFAULT} before including @file{gcrypt.h} to
1081 change this default.
1082
1083 This function can be used in callback functions to construct an error
1084 value to return it to the library.
1085 @end deftypefun
1086
1087 The @code{libgpg-error} library provides error codes for all system
1088 error numbers it knows about.  If @var{err} is an unknown error
1089 number, the error code @code{GPG_ERR_UNKNOWN_ERRNO} is used.  The
1090 following functions can be used to construct error values from system
1091 errno numbers.
1092
1093 @deftypefun {gcry_error_t} gcry_err_make_from_errno (@w{gcry_err_source_t @var{source}}, @w{int @var{err}})
1094 The function @code{gcry_err_make_from_errno} is like
1095 @code{gcry_err_make}, but it takes a system error like @code{errno}
1096 instead of a @code{gcry_err_code_t} error code.
1097 @end deftypefun
1098
1099 @deftypefun {gcry_error_t} gcry_error_from_errno (@w{int @var{err}})
1100 The function @code{gcry_error_from_errno} is like @code{gcry_error},
1101 but it takes a system error like @code{errno} instead of a
1102 @code{gcry_err_code_t} error code.
1103 @end deftypefun
1104
1105 Sometimes you might want to map system error numbers to error codes
1106 directly, or map an error code representing a system error back to the
1107 system error number.  The following functions can be used to do that.
1108
1109 @deftypefun {gcry_err_code_t} gcry_err_code_from_errno (@w{int @var{err}})
1110 The function @code{gcry_err_code_from_errno} returns the error code
1111 for the system error @var{err}.  If @var{err} is not a known system
1112 error, the function returns @code{GPG_ERR_UNKNOWN_ERRNO}.
1113 @end deftypefun
1114
1115 @deftypefun {int} gcry_err_code_to_errno (@w{gcry_err_code_t @var{err}})
1116 The function @code{gcry_err_code_to_errno} returns the system error
1117 for the error code @var{err}.  If @var{err} is not an error code
1118 representing a system error, or if this system error is not defined on
1119 this system, the function returns @code{0}.
1120 @end deftypefun
1121
1122
1123 @node Error Sources
1124 @subsection Error Sources
1125 @cindex error codes, list of
1126
1127 The library @code{libgpg-error} defines an error source for every
1128 component of the GnuPG system.  The error source part of an error
1129 value is not well defined.  As such it is mainly useful to improve the
1130 diagnostic error message for the user.
1131
1132 If the error code part of an error value is @code{0}, the whole error
1133 value will be @code{0}.  In this case the error source part is of
1134 course @code{GPG_ERR_SOURCE_UNKNOWN}.
1135
1136 The list of error sources that might occur in applications using
1137 @acronym{Libgcrypt} is:
1138
1139 @table @code
1140 @item GPG_ERR_SOURCE_UNKNOWN
1141 The error source is not known.  The value of this error source is
1142 @code{0}.
1143
1144 @item GPG_ERR_SOURCE_GPGME
1145 The error source is @acronym{GPGME} itself.
1146
1147 @item GPG_ERR_SOURCE_GPG
1148 The error source is GnuPG, which is the crypto engine used for the
1149 OpenPGP protocol.
1150
1151 @item GPG_ERR_SOURCE_GPGSM
1152 The error source is GPGSM, which is the crypto engine used for the
1153 OpenPGP protocol.
1154
1155 @item GPG_ERR_SOURCE_GCRYPT
1156 The error source is @code{libgcrypt}, which is used by crypto engines
1157 to perform cryptographic operations.
1158
1159 @item GPG_ERR_SOURCE_GPGAGENT
1160 The error source is @command{gpg-agent}, which is used by crypto
1161 engines to perform operations with the secret key.
1162
1163 @item GPG_ERR_SOURCE_PINENTRY
1164 The error source is @command{pinentry}, which is used by
1165 @command{gpg-agent} to query the passphrase to unlock a secret key.
1166
1167 @item GPG_ERR_SOURCE_SCD
1168 The error source is the SmartCard Daemon, which is used by
1169 @command{gpg-agent} to delegate operations with the secret key to a
1170 SmartCard.
1171
1172 @item GPG_ERR_SOURCE_KEYBOX
1173 The error source is @code{libkbx}, a library used by the crypto
1174 engines to manage local keyrings.
1175
1176 @item GPG_ERR_SOURCE_USER_1
1177 @item GPG_ERR_SOURCE_USER_2
1178 @item GPG_ERR_SOURCE_USER_3
1179 @item GPG_ERR_SOURCE_USER_4
1180 These error sources are not used by any GnuPG component and can be
1181 used by other software.  For example, applications using
1182 Libgcrypt can use them to mark error values coming from callback
1183 handlers.  Thus @code{GPG_ERR_SOURCE_USER_1} is the default for errors
1184 created with @code{gcry_error} and @code{gcry_error_from_errno},
1185 unless you define @code{GCRY_ERR_SOURCE_DEFAULT} before including
1186 @file{gcrypt.h}.
1187 @end table
1188
1189
1190 @node Error Codes
1191 @subsection Error Codes
1192 @cindex error codes, list of
1193
1194 The library @code{libgpg-error} defines many error values.  The
1195 following list includes the most important error codes.
1196
1197 @table @code
1198 @item GPG_ERR_EOF
1199 This value indicates the end of a list, buffer or file.
1200
1201 @item GPG_ERR_NO_ERROR
1202 This value indicates success.  The value of this error code is
1203 @code{0}.  Also, it is guaranteed that an error value made from the
1204 error code @code{0} will be @code{0} itself (as a whole).  This means
1205 that the error source information is lost for this error code,
1206 however, as this error code indicates that no error occurred, this is
1207 generally not a problem.
1208
1209 @item GPG_ERR_GENERAL
1210 This value means that something went wrong, but either there is not
1211 enough information about the problem to return a more useful error
1212 value, or there is no separate error value for this type of problem.
1213
1214 @item GPG_ERR_ENOMEM
1215 This value means that an out-of-memory condition occurred.
1216
1217 @item GPG_ERR_E...
1218 System errors are mapped to GPG_ERR_EFOO where FOO is the symbol for
1219 the system error.
1220
1221 @item GPG_ERR_INV_VALUE
1222 This value means that some user provided data was out of range.
1223
1224 @item GPG_ERR_UNUSABLE_PUBKEY
1225 This value means that some recipients for a message were invalid.
1226
1227 @item GPG_ERR_UNUSABLE_SECKEY
1228 This value means that some signers were invalid.
1229
1230 @item GPG_ERR_NO_DATA
1231 This value means that data was expected where no data was found.
1232
1233 @item GPG_ERR_CONFLICT
1234 This value means that a conflict of some sort occurred.
1235
1236 @item GPG_ERR_NOT_IMPLEMENTED
1237 This value indicates that the specific function (or operation) is not
1238 implemented.  This error should never happen.  It can only occur if
1239 you use certain values or configuration options which do not work,
1240 but for which we think that they should work at some later time.
1241
1242 @item GPG_ERR_DECRYPT_FAILED
1243 This value indicates that a decryption operation was unsuccessful.
1244
1245 @item GPG_ERR_WRONG_KEY_USAGE
1246 This value indicates that a key is not used appropriately.
1247
1248 @item GPG_ERR_NO_SECKEY
1249 This value indicates that no secret key for the user ID is available.
1250
1251 @item GPG_ERR_UNSUPPORTED_ALGORITHM
1252 This value means a verification failed because the cryptographic
1253 algorithm is not supported by the crypto backend.
1254
1255 @item GPG_ERR_BAD_SIGNATURE
1256 This value means a verification failed because the signature is bad.
1257
1258 @item GPG_ERR_NO_PUBKEY
1259 This value means a verification failed because the public key is not
1260 available.
1261
1262 @item GPG_ERR_NOT_OPERATIONAL
1263 This value means that the library is not yet in state which allows to
1264 use this function.  This error code is in particular returned if
1265 Libgcrypt is operated in FIPS mode and the internal state of the
1266 library does not yet or not anymore allow the use of a service.
1267
1268 This error code is only available with newer libgpg-error versions, thus
1269 you might see ``invalid error code'' when passing this to
1270 @code{gpg_strerror}.  The numeric value of this error code is 176.
1271
1272 @item GPG_ERR_USER_1
1273 @item GPG_ERR_USER_2
1274 @item ...
1275 @item GPG_ERR_USER_16
1276 These error codes are not used by any GnuPG component and can be
1277 freely used by other software.  Applications using Libgcrypt
1278 might use them to mark specific errors returned by callback handlers
1279 if no suitable error codes (including the system errors) for these
1280 errors exist already.
1281 @end table
1282
1283
1284 @node Error Strings
1285 @subsection Error Strings
1286 @cindex error values, printing of
1287 @cindex error codes, printing of
1288 @cindex error sources, printing of
1289 @cindex error strings
1290
1291 @deftypefun {const char *} gcry_strerror (@w{gcry_error_t @var{err}})
1292 The function @code{gcry_strerror} returns a pointer to a statically
1293 allocated string containing a description of the error code contained
1294 in the error value @var{err}.  This string can be used to output a
1295 diagnostic message to the user.
1296 @end deftypefun
1297
1298
1299 @deftypefun {const char *} gcry_strsource (@w{gcry_error_t @var{err}})
1300 The function @code{gcry_strsource} returns a pointer to a statically
1301 allocated string containing a description of the error source
1302 contained in the error value @var{err}.  This string can be used to
1303 output a diagnostic message to the user.
1304 @end deftypefun
1305
1306 The following example illustrates the use of the functions described
1307 above:
1308
1309 @example
1310 @{
1311   gcry_cipher_hd_t handle;
1312   gcry_error_t err = 0;
1313
1314   err = gcry_cipher_open (&handle, GCRY_CIPHER_AES,
1315                           GCRY_CIPHER_MODE_CBC, 0);
1316   if (err)
1317     @{
1318       fprintf (stderr, "Failure: %s/%s\n",
1319                gcry_strsource (err),
1320                gcry_strerror (err));
1321     @}
1322 @}
1323 @end example
1324
1325 @c **********************************************************
1326 @c *******************  General  ****************************
1327 @c **********************************************************
1328 @node Handler Functions
1329 @chapter Handler Functions
1330
1331 Libgcrypt makes it possible to install so called `handler functions',
1332 which get called by Libgcrypt in case of certain events.
1333
1334 @menu
1335 * Progress handler::            Using a progress handler function.
1336 * Allocation handler::          Using special memory allocation functions.
1337 * Error handler::               Using error handler functions.
1338 * Logging handler::             Using a special logging function.
1339 @end menu
1340
1341 @node Progress handler
1342 @section Progress handler
1343
1344 It is often useful to retrieve some feedback while long running
1345 operations are performed.
1346
1347 @deftp {Data type} gcry_handler_progress_t
1348 Progress handler functions have to be of the type
1349 @code{gcry_handler_progress_t}, which is defined as:
1350
1351 @code{void (*gcry_handler_progress_t) (void *, const char *, int, int, int)}
1352 @end deftp
1353
1354 The following function may be used to register a handler function for
1355 this purpose.
1356
1357 @deftypefun void gcry_set_progress_handler (gcry_handler_progress_t @var{cb}, void *@var{cb_data})
1358
1359 This function installs @var{cb} as the `Progress handler' function.
1360 It may be used only during initialization.  @var{cb} must be defined
1361 as follows:
1362
1363 @example
1364 void
1365 my_progress_handler (void *@var{cb_data}, const char *@var{what},
1366                      int @var{printchar}, int @var{current}, int @var{total})
1367 @{
1368   /* Do something.  */
1369 @}
1370 @end example
1371
1372 A description of the arguments of the progress handler function follows.
1373
1374 @table @var
1375 @item cb_data
1376 The argument provided in the call to @code{gcry_set_progress_handler}.
1377 @item what
1378 A string identifying the type of the progress output.  The following
1379 values for @var{what} are defined:
1380
1381 @table @code
1382 @item need_entropy
1383 Not enough entropy is available.  @var{total} holds the number of
1384 required bytes.
1385
1386 @item wait_dev_random
1387 Waiting to re-open a random device.  @var{total} gives the number of
1388 seconds until the next try.
1389
1390 @item primegen
1391 Values for @var{printchar}:
1392 @table @code
1393 @item \n
1394 Prime generated.
1395 @item !
1396 Need to refresh the pool of prime numbers.
1397 @item <, >
1398 Number of bits adjusted.
1399 @item ^
1400 Searching for a generator.
1401 @item .
1402 Fermat test on 10 candidates failed.
1403 @item :
1404 Restart with a new random value.
1405 @item +
1406 Rabin Miller test passed.
1407 @end table
1408
1409 @end table
1410
1411 @end table
1412 @end deftypefun
1413
1414 @node Allocation handler
1415 @section Allocation handler
1416
1417 It is possible to make Libgcrypt use special memory
1418 allocation functions instead of the built-in ones.
1419
1420 Memory allocation functions are of the following types:
1421 @deftp {Data type} gcry_handler_alloc_t
1422 This type is defined as: @code{void *(*gcry_handler_alloc_t) (size_t n)}.
1423 @end deftp
1424 @deftp {Data type} gcry_handler_secure_check_t
1425 This type is defined as: @code{int *(*gcry_handler_secure_check_t) (const void *)}.
1426 @end deftp
1427 @deftp {Data type} gcry_handler_realloc_t
1428 This type is defined as: @code{void *(*gcry_handler_realloc_t) (void *p, size_t n)}.
1429 @end deftp
1430 @deftp {Data type} gcry_handler_free_t
1431 This type is defined as: @code{void *(*gcry_handler_free_t) (void *)}.
1432 @end deftp
1433
1434 Special memory allocation functions can be installed with the
1435 following function:
1436
1437 @deftypefun void gcry_set_allocation_handler (gcry_handler_alloc_t @var{func_alloc}, gcry_handler_alloc_t @var{func_alloc_secure}, gcry_handler_secure_check_t @var{func_secure_check}, gcry_handler_realloc_t @var{func_realloc}, gcry_handler_free_t @var{func_free})
1438 Install the provided functions and use them instead of the built-in
1439 functions for doing memory allocation.  Using this function is in
1440 general not recommended because the standard Libgcrypt allocation
1441 functions are guaranteed to zeroize memory if needed.
1442
1443 This function may be used only during initialization and may not be
1444 used in fips mode.
1445
1446
1447 @end deftypefun
1448
1449 @node Error handler
1450 @section Error handler
1451
1452 The following functions may be used to register handler functions that
1453 are called by Libgcrypt in case certain error conditions occur.  They
1454 may and should be registered prior to calling @code{gcry_check_version}.
1455
1456 @deftp {Data type} gcry_handler_no_mem_t
1457 This type is defined as: @code{int (*gcry_handler_no_mem_t) (void *, size_t, unsigned int)}
1458 @end deftp
1459 @deftypefun void gcry_set_outofcore_handler (gcry_handler_no_mem_t @var{func_no_mem}, void *@var{cb_data})
1460 This function registers @var{func_no_mem} as `out-of-core handler',
1461 which means that it will be called in the case of not having enough
1462 memory available.  The handler is called with 3 arguments: The first
1463 one is the pointer @var{cb_data} as set with this function, the second
1464 is the requested memory size and the last being a flag.  If bit 0 of
1465 the flag is set, secure memory has been requested.  The handler should
1466 either return true to indicate that Libgcrypt should try again
1467 allocating memory or return false to let Libgcrypt use its default
1468 fatal error handler.
1469 @end deftypefun
1470
1471 @deftp {Data type} gcry_handler_error_t
1472 This type is defined as: @code{void (*gcry_handler_error_t) (void *, int, const char *)}
1473 @end deftp
1474
1475 @deftypefun void gcry_set_fatalerror_handler (gcry_handler_error_t @var{func_error}, void *@var{cb_data})
1476 This function registers @var{func_error} as `error handler',
1477 which means that it will be called in error conditions.
1478 @end deftypefun
1479
1480 @node Logging handler
1481 @section Logging handler
1482
1483 @deftp {Data type} gcry_handler_log_t
1484 This type is defined as: @code{void (*gcry_handler_log_t) (void *, int, const char *, va_list)}
1485 @end deftp
1486
1487 @deftypefun void gcry_set_log_handler (gcry_handler_log_t @var{func_log}, void *@var{cb_data})
1488 This function registers @var{func_log} as `logging handler', which means
1489 that it will be called in case Libgcrypt wants to log a message.  This
1490 function may and should be used prior to calling
1491 @code{gcry_check_version}.
1492 @end deftypefun
1493
1494 @c **********************************************************
1495 @c *******************  Ciphers  ****************************
1496 @c **********************************************************
1497 @c @include cipher-ref.texi
1498 @node Symmetric cryptography
1499 @chapter Symmetric cryptography
1500
1501 The cipher functions are used for symmetrical cryptography,
1502 i.e. cryptography using a shared key.  The programming model follows
1503 an open/process/close paradigm and is in that similar to other
1504 building blocks provided by Libgcrypt.
1505
1506 @menu
1507 * Available ciphers::           List of ciphers supported by the library.
1508 * Available cipher modes::      List of cipher modes supported by the library.
1509 * Working with cipher handles::  How to perform operations related to cipher handles.
1510 * General cipher functions::    General cipher functions independent of cipher handles.
1511 @end menu
1512
1513 @node Available ciphers
1514 @section Available ciphers
1515
1516 @table @code
1517 @item GCRY_CIPHER_NONE
1518 This is not a real algorithm but used by some functions as error return.
1519 The value always evaluates to false.
1520
1521 @item GCRY_CIPHER_IDEA
1522 @cindex IDEA
1523 This is the IDEA algorithm.
1524
1525 @item GCRY_CIPHER_3DES
1526 @cindex 3DES
1527 @cindex Triple-DES
1528 @cindex DES-EDE
1529 @cindex Digital Encryption Standard
1530 Triple-DES with 3 Keys as EDE.  The key size of this algorithm is 168 but
1531 you have to pass 192 bits because the most significant bits of each byte
1532 are ignored.
1533
1534 @item GCRY_CIPHER_CAST5
1535 @cindex CAST5
1536 CAST128-5 block cipher algorithm.  The key size is 128 bits.
1537
1538 @item GCRY_CIPHER_BLOWFISH
1539 @cindex Blowfish
1540 The blowfish algorithm. The current implementation allows only for a key
1541 size of 128 bits.
1542
1543 @item GCRY_CIPHER_SAFER_SK128
1544 Reserved and not currently implemented.
1545
1546 @item GCRY_CIPHER_DES_SK
1547 Reserved and not currently implemented.
1548
1549 @item  GCRY_CIPHER_AES
1550 @itemx GCRY_CIPHER_AES128
1551 @itemx GCRY_CIPHER_RIJNDAEL
1552 @itemx GCRY_CIPHER_RIJNDAEL128
1553 @cindex Rijndael
1554 @cindex AES
1555 @cindex Advanced Encryption Standard
1556 AES (Rijndael) with a 128 bit key.
1557
1558 @item  GCRY_CIPHER_AES192
1559 @itemx GCRY_CIPHER_RIJNDAEL192
1560 AES (Rijndael) with a 192 bit key.
1561
1562 @item  GCRY_CIPHER_AES256
1563 @itemx GCRY_CIPHER_RIJNDAEL256
1564 AES (Rijndael) with a 256 bit key.
1565
1566 @item  GCRY_CIPHER_TWOFISH
1567 @cindex Twofish
1568 The Twofish algorithm with a 256 bit key.
1569
1570 @item  GCRY_CIPHER_TWOFISH128
1571 The Twofish algorithm with a 128 bit key.
1572
1573 @item  GCRY_CIPHER_ARCFOUR
1574 @cindex Arcfour
1575 @cindex RC4
1576 An algorithm which is 100% compatible with RSA Inc.'s RC4 algorithm.
1577 Note that this is a stream cipher and must be used very carefully to
1578 avoid a couple of weaknesses.
1579
1580 @item  GCRY_CIPHER_DES
1581 @cindex DES
1582 Standard DES with a 56 bit key. You need to pass 64 bit but the high
1583 bits of each byte are ignored.  Note, that this is a weak algorithm
1584 which can be broken in reasonable time using a brute force approach.
1585
1586 @item  GCRY_CIPHER_SERPENT128
1587 @itemx GCRY_CIPHER_SERPENT192
1588 @itemx GCRY_CIPHER_SERPENT256
1589 @cindex Serpent
1590 The Serpent cipher from the AES contest.
1591
1592 @item  GCRY_CIPHER_RFC2268_40
1593 @itemx GCRY_CIPHER_RFC2268_128
1594 @cindex rfc-2268
1595 @cindex RC2
1596 Ron's Cipher 2 in the 40 and 128 bit variants.
1597
1598 @item GCRY_CIPHER_SEED
1599 @cindex Seed (cipher)
1600 A 128 bit cipher as described by RFC4269.
1601
1602 @item  GCRY_CIPHER_CAMELLIA128
1603 @itemx GCRY_CIPHER_CAMELLIA192
1604 @itemx GCRY_CIPHER_CAMELLIA256
1605 @cindex Camellia
1606 The Camellia cipher by NTT.  See
1607 @uref{http://info.isl.ntt.co.jp/@/crypt/@/eng/@/camellia/@/specifications.html}.
1608
1609 @item GCRY_CIPHER_SALSA20
1610 @cindex Salsa20
1611 This is the Salsa20 stream cipher.
1612
1613 @item GCRY_CIPHER_SALSA20R12
1614 @cindex Salsa20/12
1615 This is the Salsa20/12 - reduced round version of Salsa20 stream cipher.
1616
1617 @item GCRY_CIPHER_GOST28147
1618 @cindex GOST 28147-89
1619 The GOST 28147-89 cipher, defined in the respective GOST standard.
1620 Translation of this GOST into English is provided in the RFC-5830.
1621
1622 @item GCRY_CIPHER_CHACHA20
1623 @cindex ChaCha20
1624 This is the ChaCha20 stream cipher.
1625
1626 @end table
1627
1628 @node Available cipher modes
1629 @section Available cipher modes
1630
1631 @table @code
1632 @item GCRY_CIPHER_MODE_NONE
1633 No mode specified.  This should not be used.  The only exception is that
1634 if Libgcrypt is not used in FIPS mode and if any debug flag has been
1635 set, this mode may be used to bypass the actual encryption.
1636
1637 @item GCRY_CIPHER_MODE_ECB
1638 @cindex ECB, Electronic Codebook mode
1639 Electronic Codebook mode.
1640
1641 @item GCRY_CIPHER_MODE_CFB
1642 @item GCRY_CIPHER_MODE_CFB8
1643 @cindex CFB, Cipher Feedback mode
1644 Cipher Feedback mode.  For GCRY_CIPHER_MODE_CFB the shift size equals
1645 the block size of the cipher (e.g. for AES it is CFB-128).  For
1646 GCRY_CIPHER_MODE_CFB8 the shift size is 8 bit but that variant is not
1647 yet available.
1648
1649 @item  GCRY_CIPHER_MODE_CBC
1650 @cindex CBC, Cipher Block Chaining mode
1651 Cipher Block Chaining mode.
1652
1653 @item GCRY_CIPHER_MODE_STREAM
1654 Stream mode, only to be used with stream cipher algorithms.
1655
1656 @item GCRY_CIPHER_MODE_OFB
1657 @cindex OFB, Output Feedback mode
1658 Output Feedback mode.
1659
1660 @item  GCRY_CIPHER_MODE_CTR
1661 @cindex CTR, Counter mode
1662 Counter mode.
1663
1664 @item  GCRY_CIPHER_MODE_AESWRAP
1665 @cindex AES-Wrap mode
1666 This mode is used to implement the AES-Wrap algorithm according to
1667 RFC-3394.  It may be used with any 128 bit block length algorithm,
1668 however the specs require one of the 3 AES algorithms.  These special
1669 conditions apply: If @code{gcry_cipher_setiv} has not been used the
1670 standard IV is used; if it has been used the lower 64 bit of the IV
1671 are used as the Alternative Initial Value.  On encryption the provided
1672 output buffer must be 64 bit (8 byte) larger than the input buffer;
1673 in-place encryption is still allowed.  On decryption the output buffer
1674 may be specified 64 bit (8 byte) shorter than then input buffer.  As
1675 per specs the input length must be at least 128 bits and the length
1676 must be a multiple of 64 bits.
1677
1678 @item  GCRY_CIPHER_MODE_CCM
1679 @cindex CCM, Counter with CBC-MAC mode
1680 Counter with CBC-MAC mode is an Authenticated Encryption with
1681 Associated Data (AEAD) block cipher mode, which is specified in
1682 'NIST Special Publication 800-38C' and RFC 3610.
1683
1684 @item  GCRY_CIPHER_MODE_GCM
1685 @cindex GCM, Galois/Counter Mode
1686 Galois/Counter Mode (GCM) is an Authenticated Encryption with
1687 Associated Data (AEAD) block cipher mode, which is specified in
1688 'NIST Special Publication 800-38D'.
1689
1690 @item  GCRY_CIPHER_MODE_POLY1305
1691 @cindex Poly1305 based AEAD mode with ChaCha20
1692 This mode implements the Poly1305 Authenticated Encryption with Associated
1693 Data (AEAD) mode according to RFC-8439. This mode can be used with ChaCha20
1694 stream cipher.
1695
1696 @item  GCRY_CIPHER_MODE_OCB
1697 @cindex OCB, OCB3
1698 OCB is an Authenticated Encryption with Associated Data (AEAD) block
1699 cipher mode, which is specified in RFC-7253.  Supported tag lengths
1700 are 128, 96, and 64 bit with the default being 128 bit.  To switch to
1701 a different tag length @code{gcry_cipher_ctl} using the command
1702 @code{GCRYCTL_SET_TAGLEN} and the address of an @code{int} variable
1703 set to 12 (for 96 bit) or 8 (for 64 bit) provided for the
1704 @code{buffer} argument and @code{sizeof(int)} for @code{buflen}.
1705
1706 Note that the use of @code{gcry_cipher_final} is required.
1707
1708 @item  GCRY_CIPHER_MODE_XTS
1709 @cindex XTS, XTS mode
1710 XEX-based tweaked-codebook mode with ciphertext stealing (XTS) mode
1711 is used to implement the AES-XTS as specified in IEEE 1619 Standard
1712 Architecture for Encrypted Shared Storage Media and NIST SP800-38E.
1713
1714 The XTS mode requires doubling key-length, for example, using 512-bit
1715 key with AES-256 (@code{GCRY_CIPHER_AES256}). The 128-bit tweak value
1716 is feed to XTS mode as little-endian byte array using
1717 @code{gcry_cipher_setiv} function. When encrypting or decrypting,
1718 full-sized data unit buffers needs to be passed to
1719 @code{gcry_cipher_encrypt} or @code{gcry_cipher_decrypt}. The tweak
1720 value is automatically incremented after each call of
1721 @code{gcry_cipher_encrypt} and @code{gcry_cipher_decrypt}.
1722 Auto-increment allows avoiding need of setting IV between processing
1723 of sequential data units.
1724
1725 @item  GCRY_CIPHER_MODE_EAX
1726 @cindex EAX, EAX mode
1727 EAX is an Authenticated Encryption with Associated Data (AEAD) block cipher
1728 mode by Bellare, Rogaway, and Wagner (see
1729 @uref{http://web.cs.ucdavis.edu/~rogaway/papers/eax.html}).
1730
1731 @end table
1732
1733 @node Working with cipher handles
1734 @section Working with cipher handles
1735
1736 To use a cipher algorithm, you must first allocate an according
1737 handle.  This is to be done using the open function:
1738
1739 @deftypefun gcry_error_t gcry_cipher_open (gcry_cipher_hd_t *@var{hd}, int @var{algo}, int @var{mode}, unsigned int @var{flags})
1740
1741 This function creates the context handle required for most of the
1742 other cipher functions and returns a handle to it in `hd'.  In case of
1743 an error, an according error code is returned.
1744
1745 The ID of algorithm to use must be specified via @var{algo}.  See
1746 @ref{Available ciphers}, for a list of supported ciphers and the
1747 according constants.
1748
1749 Besides using the constants directly, the function
1750 @code{gcry_cipher_map_name} may be used to convert the textual name of
1751 an algorithm into the according numeric ID.
1752
1753 The cipher mode to use must be specified via @var{mode}.  See
1754 @ref{Available cipher modes}, for a list of supported cipher modes
1755 and the according constants.  Note that some modes are incompatible
1756 with some algorithms - in particular, stream mode
1757 (@code{GCRY_CIPHER_MODE_STREAM}) only works with stream ciphers.
1758 Poly1305 AEAD mode (@code{GCRY_CIPHER_MODE_POLY1305}) only works with
1759 ChaCha20 stream cipher. The block cipher modes
1760 (@code{GCRY_CIPHER_MODE_ECB}, @code{GCRY_CIPHER_MODE_CBC},
1761 @code{GCRY_CIPHER_MODE_CFB}, @code{GCRY_CIPHER_MODE_OFB},
1762 @code{GCRY_CIPHER_MODE_CTR} and @code{GCRY_CIPHER_MODE_EAX}) will work
1763 with any block cipher algorithm.  GCM mode
1764 (@code{GCRY_CIPHER_MODE_CCM}), CCM mode (@code{GCRY_CIPHER_MODE_GCM}),
1765 OCB mode (@code{GCRY_CIPHER_MODE_OCB}), and XTS mode
1766 (@code{GCRY_CIPHER_MODE_XTS}) will only work with block cipher
1767 algorithms which have the block size of 16 bytes.
1768
1769 The third argument @var{flags} can either be passed as @code{0} or as
1770 the bit-wise OR of the following constants.
1771
1772 @table @code
1773 @item GCRY_CIPHER_SECURE
1774 Make sure that all operations are allocated in secure memory.  This is
1775 useful when the key material is highly confidential.
1776 @item GCRY_CIPHER_ENABLE_SYNC
1777 @cindex sync mode (OpenPGP)
1778 This flag enables the CFB sync mode, which is a special feature of
1779 Libgcrypt's CFB mode implementation to allow for OpenPGP's CFB variant.
1780 See @code{gcry_cipher_sync}.
1781 @item GCRY_CIPHER_CBC_CTS
1782 @cindex cipher text stealing
1783 Enable cipher text stealing (CTS) for the CBC mode.  Cannot be used
1784 simultaneous as GCRY_CIPHER_CBC_MAC.  CTS mode makes it possible to
1785 transform data of almost arbitrary size (only limitation is that it
1786 must be greater than the algorithm's block size).
1787 @item GCRY_CIPHER_CBC_MAC
1788 @cindex CBC-MAC
1789 Compute CBC-MAC keyed checksums.  This is the same as CBC mode, but
1790 only output the last block.  Cannot be used simultaneous as
1791 GCRY_CIPHER_CBC_CTS.
1792 @end table
1793 @end deftypefun
1794
1795 Use the following function to release an existing handle:
1796
1797 @deftypefun void gcry_cipher_close (gcry_cipher_hd_t @var{h})
1798
1799 This function releases the context created by @code{gcry_cipher_open}.
1800 It also zeroises all sensitive information associated with this cipher
1801 handle.
1802 @end deftypefun
1803
1804 In order to use a handle for performing cryptographic operations, a
1805 `key' has to be set first:
1806
1807 @deftypefun gcry_error_t gcry_cipher_setkey (gcry_cipher_hd_t @var{h}, const void *@var{k}, size_t @var{l})
1808
1809 Set the key @var{k} used for encryption or decryption in the context
1810 denoted by the handle @var{h}.  The length @var{l} (in bytes) of the
1811 key @var{k} must match the required length of the algorithm set for
1812 this context or be in the allowed range for algorithms with variable
1813 key size.  The function checks this and returns an error if there is a
1814 problem.  A caller should always check for an error.
1815
1816 @end deftypefun
1817
1818 Most crypto modes requires an initialization vector (IV), which
1819 usually is a non-secret random string acting as a kind of salt value.
1820 The CTR mode requires a counter, which is also similar to a salt
1821 value.  To set the IV or CTR, use these functions:
1822
1823 @deftypefun gcry_error_t gcry_cipher_setiv (gcry_cipher_hd_t @var{h}, const void *@var{k}, size_t @var{l})
1824
1825 Set the initialization vector used for encryption or decryption. The
1826 vector is passed as the buffer @var{K} of length @var{l} bytes and
1827 copied to internal data structures.  The function checks that the IV
1828 matches the requirement of the selected algorithm and mode.
1829
1830 This function is also used by AEAD modes and with Salsa20 and ChaCha20
1831 stream ciphers to set or update the required nonce.  In these cases it
1832 needs to be called after setting the key.
1833
1834 @end deftypefun
1835
1836 @deftypefun gcry_error_t gcry_cipher_setctr (gcry_cipher_hd_t @var{h}, const void *@var{c}, size_t @var{l})
1837
1838 Set the counter vector used for encryption or decryption. The counter
1839 is passed as the buffer @var{c} of length @var{l} bytes and copied to
1840 internal data structures.  The function checks that the counter
1841 matches the requirement of the selected algorithm (i.e., it must be
1842 the same size as the block size).
1843 @end deftypefun
1844
1845 @deftypefun gcry_error_t gcry_cipher_reset (gcry_cipher_hd_t @var{h})
1846
1847 Set the given handle's context back to the state it had after the last
1848 call to gcry_cipher_setkey and clear the initialization vector.
1849
1850 Note that gcry_cipher_reset is implemented as a macro.
1851 @end deftypefun
1852
1853 Authenticated Encryption with Associated Data (AEAD) block cipher
1854 modes require the handling of the authentication tag and the additional
1855 authenticated data, which can be done by using the following
1856 functions:
1857
1858 @deftypefun gcry_error_t gcry_cipher_authenticate (gcry_cipher_hd_t @var{h}, const void *@var{abuf}, size_t @var{abuflen})
1859
1860 Process the buffer @var{abuf} of length @var{abuflen} as the additional
1861 authenticated data (AAD) for AEAD cipher modes.
1862
1863 @end deftypefun
1864
1865 @deftypefun {gcry_error_t} gcry_cipher_gettag @
1866             (@w{gcry_cipher_hd_t @var{h}}, @
1867             @w{void *@var{tag}}, @w{size_t @var{taglen}})
1868
1869 This function is used to read the authentication tag after encryption.
1870 The function finalizes and outputs the authentication tag to the buffer
1871 @var{tag} of length @var{taglen} bytes.
1872
1873 Depending on the used mode certain restrictions for @var{taglen} are
1874 enforced:  For GCM @var{taglen} must be at least 16 or one of the
1875 allowed truncated lengths (4, 8, 12, 13, 14, or 15).
1876
1877 @end deftypefun
1878
1879 @deftypefun {gcry_error_t} gcry_cipher_checktag @
1880             (@w{gcry_cipher_hd_t @var{h}}, @
1881             @w{const void *@var{tag}}, @w{size_t @var{taglen}})
1882
1883 Check the authentication tag after decryption. The authentication
1884 tag is passed as the buffer @var{tag} of length @var{taglen} bytes
1885 and compared to internal authentication tag computed during
1886 decryption.  Error code @code{GPG_ERR_CHECKSUM} is returned if
1887 the authentication tag in the buffer @var{tag} does not match
1888 the authentication tag calculated during decryption.
1889
1890 Depending on the used mode certain restrictions for @var{taglen} are
1891 enforced: For GCM @var{taglen} must either be 16 or one of the allowed
1892 truncated lengths (4, 8, 12, 13, 14, or 15).
1893
1894 @end deftypefun
1895
1896 The actual encryption and decryption is done by using one of the
1897 following functions.  They may be used as often as required to process
1898 all the data.
1899
1900 @deftypefun gcry_error_t gcry_cipher_encrypt (gcry_cipher_hd_t @var{h}, unsigned char *{out}, size_t @var{outsize}, const unsigned char *@var{in}, size_t @var{inlen})
1901
1902 @code{gcry_cipher_encrypt} is used to encrypt the data.  This function
1903 can either work in place or with two buffers.  It uses the cipher
1904 context already setup and described by the handle @var{h}.  There are 2
1905 ways to use the function: If @var{in} is passed as @code{NULL} and
1906 @var{inlen} is @code{0}, in-place encryption of the data in @var{out} of
1907 length @var{outsize} takes place.  With @var{in} being not @code{NULL},
1908 @var{inlen} bytes are encrypted to the buffer @var{out} which must have
1909 at least a size of @var{inlen}.  @var{outsize} must be set to the
1910 allocated size of @var{out}, so that the function can check that there
1911 is sufficient space. Note that overlapping buffers are not allowed.
1912
1913 Depending on the selected algorithms and encryption mode, the length of
1914 the buffers must be a multiple of the block size.
1915
1916 Some encryption modes require that @code{gcry_cipher_final} is used
1917 before the final data chunk is passed to this function.
1918
1919 The function returns @code{0} on success or an error code.
1920 @end deftypefun
1921
1922
1923 @deftypefun gcry_error_t gcry_cipher_decrypt (gcry_cipher_hd_t @var{h}, unsigned char *{out}, size_t @var{outsize}, const unsigned char *@var{in}, size_t @var{inlen})
1924
1925 @code{gcry_cipher_decrypt} is used to decrypt the data.  This function
1926 can either work in place or with two buffers.  It uses the cipher
1927 context already setup and described by the handle @var{h}.  There are 2
1928 ways to use the function: If @var{in} is passed as @code{NULL} and
1929 @var{inlen} is @code{0}, in-place decryption of the data in @var{out} or
1930 length @var{outsize} takes place.  With @var{in} being not @code{NULL},
1931 @var{inlen} bytes are decrypted to the buffer @var{out} which must have
1932 at least a size of @var{inlen}.  @var{outsize} must be set to the
1933 allocated size of @var{out}, so that the function can check that there
1934 is sufficient space.  Note that overlapping buffers are not allowed.
1935
1936 Depending on the selected algorithms and encryption mode, the length of
1937 the buffers must be a multiple of the block size.
1938
1939 Some encryption modes require that @code{gcry_cipher_final} is used
1940 before the final data chunk is passed to this function.
1941
1942 The function returns @code{0} on success or an error code.
1943 @end deftypefun
1944
1945
1946 The OCB mode features integrated padding and must thus be told about
1947 the end of the input data. This is done with:
1948
1949 @deftypefun gcry_error_t gcry_cipher_final (gcry_cipher_hd_t @var{h})
1950
1951 Set a flag in the context to tell the encrypt and decrypt functions
1952 that their next call will provide the last chunk of data.  Only the
1953 first call to this function has an effect and only for modes which
1954 support it.  Checking the error is in general not necessary.  This is
1955 implemented as a macro.
1956 @end deftypefun
1957
1958
1959 OpenPGP (as defined in RFC-4880) requires a special sync operation in
1960 some places.  The following function is used for this:
1961
1962 @deftypefun gcry_error_t gcry_cipher_sync (gcry_cipher_hd_t @var{h})
1963
1964 Perform the OpenPGP sync operation on context @var{h}.  Note that this
1965 is a no-op unless the context was created with the flag
1966 @code{GCRY_CIPHER_ENABLE_SYNC}
1967 @end deftypefun
1968
1969 Some of the described functions are implemented as macros utilizing a
1970 catch-all control function.  This control function is rarely used
1971 directly but there is nothing which would inhibit it:
1972
1973 @deftypefun gcry_error_t gcry_cipher_ctl (gcry_cipher_hd_t @var{h}, int @var{cmd}, void *@var{buffer}, size_t @var{buflen})
1974
1975 @code{gcry_cipher_ctl} controls various aspects of the cipher module and
1976 specific cipher contexts.  Usually some more specialized functions or
1977 macros are used for this purpose.  The semantics of the function and its
1978 parameters depends on the the command @var{cmd} and the passed context
1979 handle @var{h}.  Please see the comments in the source code
1980 (@code{src/global.c}) for details.
1981 @end deftypefun
1982
1983 @deftypefun gcry_error_t gcry_cipher_info (gcry_cipher_hd_t @var{h}, @
1984               int @var{what}, void *@var{buffer}, size_t *@var{nbytes})
1985
1986 @code{gcry_cipher_info} is used to retrieve various
1987 information about a cipher context or the cipher module in general.
1988
1989 @c begin constants for gcry_cipher_info
1990 @table @code
1991
1992 @item GCRYCTL_GET_TAGLEN:
1993 Return the length of the tag for an AE algorithm mode.  An error is
1994 returned for modes which do not support a tag.  @var{buffer} must be
1995 given as NULL.  On success the result is stored @var{nbytes}.  The
1996 taglen is returned in bytes.
1997
1998 @end table
1999 @c end constants for gcry_cipher_info
2000
2001 @end deftypefun
2002
2003 @node General cipher functions
2004 @section General cipher functions
2005
2006 To work with the algorithms, several functions are available to map
2007 algorithm names to the internal identifiers, as well as ways to
2008 retrieve information about an algorithm or the current cipher context.
2009
2010 @deftypefun gcry_error_t gcry_cipher_algo_info (int @var{algo}, int @var{what}, void *@var{buffer}, size_t *@var{nbytes})
2011
2012 This function is used to retrieve information on a specific algorithm.
2013 You pass the cipher algorithm ID as @var{algo} and the type of
2014 information requested as @var{what}. The result is either returned as
2015 the return code of the function or copied to the provided @var{buffer}
2016 whose allocated length must be available in an integer variable with the
2017 address passed in @var{nbytes}.  This variable will also receive the
2018 actual used length of the buffer.
2019
2020 Here is a list of supported codes for @var{what}:
2021
2022 @c begin constants for gcry_cipher_algo_info
2023 @table @code
2024 @item GCRYCTL_GET_KEYLEN:
2025 Return the length of the key. If the algorithm supports multiple key
2026 lengths, the maximum supported value is returned.  The length is
2027 returned as number of octets (bytes) and not as number of bits in
2028 @var{nbytes}; @var{buffer} must be zero.  Note that it is usually
2029 better to use the convenience function
2030 @code{gcry_cipher_get_algo_keylen}.
2031
2032 @item GCRYCTL_GET_BLKLEN:
2033 Return the block length of the algorithm.  The length is returned as a
2034 number of octets in @var{nbytes}; @var{buffer} must be zero.  Note
2035 that it is usually better to use the convenience function
2036 @code{gcry_cipher_get_algo_blklen}.
2037
2038 @item GCRYCTL_TEST_ALGO:
2039 Returns @code{0} when the specified algorithm is available for use.
2040 @var{buffer} and @var{nbytes} must be zero.
2041
2042 @end table
2043 @c end constants for gcry_cipher_algo_info
2044
2045 @end deftypefun
2046 @c end gcry_cipher_algo_info
2047
2048 @deftypefun size_t gcry_cipher_get_algo_keylen (@var{algo})
2049
2050 This function returns length of the key for algorithm @var{algo}.  If
2051 the algorithm supports multiple key lengths, the maximum supported key
2052 length is returned.  On error @code{0} is returned.  The key length is
2053 returned as number of octets.
2054
2055 This is a convenience functions which should be preferred over
2056 @code{gcry_cipher_algo_info} because it allows for proper type
2057 checking.
2058 @end deftypefun
2059 @c end gcry_cipher_get_algo_keylen
2060
2061 @deftypefun size_t gcry_cipher_get_algo_blklen (int @var{algo})
2062
2063 This functions returns the block-length of the algorithm @var{algo}
2064 counted in octets.  On error @code{0} is returned.
2065
2066 This is a convenience functions which should be preferred over
2067 @code{gcry_cipher_algo_info} because it allows for proper type
2068 checking.
2069 @end deftypefun
2070 @c end gcry_cipher_get_algo_blklen
2071
2072
2073 @deftypefun {const char *} gcry_cipher_algo_name (int @var{algo})
2074
2075 @code{gcry_cipher_algo_name} returns a string with the name of the
2076 cipher algorithm @var{algo}.  If the algorithm is not known or another
2077 error occurred, the string @code{"?"} is returned.  This function should
2078 not be used to test for the availability of an algorithm.
2079 @end deftypefun
2080
2081 @deftypefun int gcry_cipher_map_name (const char *@var{name})
2082
2083 @code{gcry_cipher_map_name} returns the algorithm identifier for the
2084 cipher algorithm described by the string @var{name}.  If this algorithm
2085 is not available @code{0} is returned.
2086 @end deftypefun
2087
2088 @deftypefun int gcry_cipher_mode_from_oid (const char *@var{string})
2089
2090 Return the cipher mode associated with an @acronym{ASN.1} object
2091 identifier.  The object identifier is expected to be in the
2092 @acronym{IETF}-style dotted decimal notation.  The function returns
2093 @code{0} for an unknown object identifier or when no mode is associated
2094 with it.
2095 @end deftypefun
2096
2097
2098 @c **********************************************************
2099 @c *******************  Public Key  *************************
2100 @c **********************************************************
2101 @node Public Key cryptography
2102 @chapter Public Key cryptography
2103
2104 Public key cryptography, also known as asymmetric cryptography, is an
2105 easy way for key management and to provide digital signatures.
2106 Libgcrypt provides two completely different interfaces to
2107 public key cryptography, this chapter explains the one based on
2108 S-expressions.
2109
2110 @menu
2111 * Available algorithms::        Algorithms supported by the library.
2112 * Used S-expressions::          Introduction into the used S-expression.
2113 * Cryptographic Functions::     Functions for performing the cryptographic actions.
2114 * General public-key related Functions::  General functions, not implementing any cryptography.
2115 @end menu
2116
2117 @node Available algorithms
2118 @section Available algorithms
2119
2120 Libgcrypt supports the RSA (Rivest-Shamir-Adleman) algorithms as well
2121 as DSA (Digital Signature Algorithm) and Elgamal.  The versatile
2122 interface allows to add more algorithms in the future.
2123
2124 @node Used S-expressions
2125 @section Used S-expressions
2126
2127 Libgcrypt's API for asymmetric cryptography is based on data structures
2128 called S-expressions (see
2129 @uref{http://people.csail.mit.edu/@/rivest/@/sexp.html}) and does not work
2130 with contexts as most of the other building blocks of Libgcrypt do.
2131
2132 @noindent
2133 The following information are stored in S-expressions:
2134
2135 @itemize
2136 @item keys
2137
2138 @item plain text data
2139
2140 @item encrypted data
2141
2142 @item signatures
2143
2144 @end itemize
2145
2146 @noindent
2147 To describe how Libgcrypt expect keys, we use examples. Note that
2148 words in
2149 @ifnottex
2150 uppercase
2151 @end ifnottex
2152 @iftex
2153 italics
2154 @end iftex
2155 indicate parameters whereas lowercase words are literals.
2156
2157 Note that all MPI (multi-precision-integers) values are expected to be in
2158 @code{GCRYMPI_FMT_USG} format.  An easy way to create S-expressions is
2159 by using @code{gcry_sexp_build} which allows to pass a string with
2160 printf-like escapes to insert MPI values.
2161
2162 @menu
2163 * RSA key parameters::  Parameters used with an RSA key.
2164 * DSA key parameters::  Parameters used with a DSA key.
2165 * ECC key parameters::  Parameters used with ECC keys.
2166 @end menu
2167
2168 @node RSA key parameters
2169 @subsection RSA key parameters
2170
2171 @noindent
2172 An RSA private key is described by this S-expression:
2173
2174 @example
2175 (private-key
2176   (rsa
2177     (n @var{n-mpi})
2178     (e @var{e-mpi})
2179     (d @var{d-mpi})
2180     (p @var{p-mpi})
2181     (q @var{q-mpi})
2182     (u @var{u-mpi})))
2183 @end example
2184
2185 @noindent
2186 An RSA public key is described by this S-expression:
2187
2188 @example
2189 (public-key
2190   (rsa
2191     (n @var{n-mpi})
2192     (e @var{e-mpi})))
2193 @end example
2194
2195
2196 @table @var
2197 @item n-mpi
2198 RSA public modulus @math{n}.
2199 @item e-mpi
2200 RSA public exponent @math{e}.
2201 @item d-mpi
2202 RSA secret exponent @math{d = e^{-1} \bmod (p-1)(q-1)}.
2203 @item p-mpi
2204 RSA secret prime @math{p}.
2205 @item q-mpi
2206 RSA secret prime @math{q} with @math{p < q}.
2207 @item u-mpi
2208 Multiplicative inverse @math{u = p^{-1} \bmod q}.
2209 @end table
2210
2211 For signing and decryption the parameters @math{(p, q, u)} are optional
2212 but greatly improve the performance.  Either all of these optional
2213 parameters must be given or none of them.  They are mandatory for
2214 gcry_pk_testkey.
2215
2216 Note that OpenSSL uses slighly different parameters: @math{q < p} and
2217  @math{u = q^{-1} \bmod p}.  To use these parameters you will need to
2218 swap the values and recompute @math{u}.  Here is example code to do this:
2219
2220 @example
2221   if (gcry_mpi_cmp (p, q) > 0)
2222     @{
2223       gcry_mpi_swap (p, q);
2224       gcry_mpi_invm (u, p, q);
2225     @}
2226 @end example
2227
2228
2229
2230
2231 @node DSA key parameters
2232 @subsection DSA key parameters
2233
2234 @noindent
2235 A DSA private key is described by this S-expression:
2236
2237 @example
2238 (private-key
2239   (dsa
2240     (p @var{p-mpi})
2241     (q @var{q-mpi})
2242     (g @var{g-mpi})
2243     (y @var{y-mpi})
2244     (x @var{x-mpi})))
2245 @end example
2246
2247 @table @var
2248 @item p-mpi
2249 DSA prime @math{p}.
2250 @item q-mpi
2251 DSA group order @math{q} (which is a prime divisor of @math{p-1}).
2252 @item g-mpi
2253 DSA group generator @math{g}.
2254 @item y-mpi
2255 DSA public key value @math{y = g^x \bmod p}.
2256 @item x-mpi
2257 DSA secret exponent x.
2258 @end table
2259
2260 The public key is similar with "private-key" replaced by "public-key"
2261 and no @var{x-mpi}.
2262
2263
2264 @node ECC key parameters
2265 @subsection ECC key parameters
2266
2267 @anchor{ecc_keyparam}
2268 @noindent
2269 An ECC private key is described by this S-expression:
2270
2271 @example
2272 (private-key
2273   (ecc
2274     (p @var{p-mpi})
2275     (a @var{a-mpi})
2276     (b @var{b-mpi})
2277     (g @var{g-point})
2278     (n @var{n-mpi})
2279     (q @var{q-point})
2280     (d @var{d-mpi})))
2281 @end example
2282
2283 @table @var
2284 @item p-mpi
2285 Prime specifying the field @math{GF(p)}.
2286 @item a-mpi
2287 @itemx b-mpi
2288 The two coefficients of the Weierstrass equation @math{y^2 = x^3 + ax + b}
2289 @item g-point
2290 Base point @math{g}.
2291 @item n-mpi
2292 Order of @math{g}
2293 @item q-point
2294 The point representing the public key @math{Q = dG}.
2295 @item d-mpi
2296 The private key @math{d}
2297 @end table
2298
2299 All point values are encoded in standard format; Libgcrypt does in
2300 general only support uncompressed points, thus the first byte needs to
2301 be @code{0x04}.  However ``EdDSA'' describes its own compression
2302 scheme which is used by default; the non-standard first byte
2303 @code{0x40} may optionally be used to explicit flag the use of the
2304 algorithm’s native compression method.
2305
2306 The public key is similar with "private-key" replaced by "public-key"
2307 and no @var{d-mpi}.
2308
2309 If the domain parameters are well-known, the name of this curve may be
2310 used.  For example
2311
2312 @example
2313 (private-key
2314   (ecc
2315     (curve "NIST P-192")
2316     (q @var{q-point})
2317     (d @var{d-mpi})))
2318 @end example
2319
2320 Note that @var{q-point} is optional for a private key.  The
2321 @code{curve} parameter may be given in any case and is used to replace
2322 missing parameters.
2323
2324 @noindent
2325 Currently implemented curves are:
2326 @table @code
2327 @item NIST P-192
2328 @itemx 1.2.840.10045.3.1.1
2329 @itemx prime192v1
2330 @itemx secp192r1
2331 The NIST 192 bit curve, its OID, X9.62 and SECP aliases.
2332
2333 @item NIST P-224
2334 @itemx secp224r1
2335 The NIST 224 bit curve and its SECP alias.
2336
2337 @item NIST P-256
2338 @itemx 1.2.840.10045.3.1.7
2339 @itemx prime256v1
2340 @itemx secp256r1
2341 The NIST 256 bit curve, its OID, X9.62 and SECP aliases.
2342
2343 @item NIST P-384
2344 @itemx secp384r1
2345 The NIST 384 bit curve and its SECP alias.
2346
2347 @item NIST P-521
2348 @itemx secp521r1
2349 The NIST 521 bit curve and its SECP alias.
2350
2351 @end table
2352 As usual the OIDs may optionally be prefixed with the string @code{OID.}
2353 or @code{oid.}.
2354
2355
2356 @node Cryptographic Functions
2357 @section Cryptographic Functions
2358
2359 @noindent
2360 Some functions operating on S-expressions support `flags' to influence
2361 the operation.  These flags have to be listed in a sub-S-expression
2362 named `flags'.  Flag names are case-sensitive.  The following flags
2363 are known:
2364
2365 @table @code
2366
2367 @item comp
2368 @itemx nocomp
2369 @cindex comp
2370 @cindex nocomp
2371 If supported by the algorithm and curve the @code{comp} flag requests
2372 that points are returned in compact (compressed) representation.  The
2373 @code{nocomp} flag requests that points are returned with full
2374 coordinates.  The default depends on the the algorithm and curve.  The
2375 compact representation requires a small overhead before a point can be
2376 used but halves the size of a to be conveyed public key.  If
2377 @code{comp} is used with the ``EdDSA'' algorithm the key generation
2378 prefix the public key with a @code{0x40} byte.
2379
2380 @item pkcs1
2381 @cindex PKCS1
2382 Use PKCS#1 block type 2 padding for encryption, block type 1 padding
2383 for signing.
2384
2385 @item oaep
2386 @cindex OAEP
2387 Use RSA-OAEP padding for encryption.
2388
2389 @item pss
2390 @cindex PSS
2391 Use RSA-PSS padding for signing.
2392
2393 @item eddsa
2394 @cindex EdDSA
2395 Use the EdDSA scheme signing instead of the default ECDSA algorithm.
2396 Note that the EdDSA uses a special form of the public key.
2397
2398 @item rfc6979
2399 @cindex RFC6979
2400 For DSA and ECDSA use a deterministic scheme for the k parameter.
2401
2402 @item no-blinding
2403 @cindex no-blinding
2404 Do not use a technique called `blinding', which is used by default in
2405 order to prevent leaking of secret information.  Blinding is only
2406 implemented by RSA, but it might be implemented by other algorithms in
2407 the future as well, when necessary.
2408
2409 @item param
2410 @cindex param
2411 For ECC key generation also return the domain parameters.  For ECC
2412 signing and verification override default parameters by provided
2413 domain parameters of the public or private key.
2414
2415 @item transient-key
2416 @cindex transient-key
2417 This flag is only meaningful for RSA, DSA, and ECC key generation.  If
2418 given the key is created using a faster and a somewhat less secure
2419 random number generator.  This flag may be used for keys which are
2420 only used for a short time or per-message and do not require full
2421 cryptographic strength.
2422
2423 @item no-keytest
2424 @cindex no-keytest
2425 This flag skips internal failsafe tests to assert that a generated key
2426 is properly working.  It currently has an effect only for standard ECC
2427 key generation.  It is mostly useful along with transient-key to
2428 achieve fastest ECC key generation.
2429
2430 @item use-x931
2431 @cindex X9.31
2432 Force the use of the ANSI X9.31 key generation algorithm instead of
2433 the default algorithm. This flag is only meaningful for RSA key
2434 generation and usually not required.  Note that this algorithm is
2435 implicitly used if either @code{derive-parms} is given or Libgcrypt is
2436 in FIPS mode.
2437
2438 @item use-fips186
2439 @cindex FIPS 186
2440 Force the use of the FIPS 186 key generation algorithm instead of the
2441 default algorithm.  This flag is only meaningful for DSA and usually
2442 not required.  Note that this algorithm is implicitly used if either
2443 @code{derive-parms} is given or Libgcrypt is in FIPS mode.  As of now
2444 FIPS 186-2 is implemented; after the approval of FIPS 186-3 the code
2445 will be changed to implement 186-3.
2446
2447 @item use-fips186-2
2448 @cindex FIPS 186-2
2449 Force the use of the FIPS 186-2 key generation algorithm instead of
2450 the default algorithm.  This algorithm is slightly different from
2451 FIPS 186-3 and allows only 1024 bit keys.  This flag is only meaningful
2452 for DSA and only required for FIPS testing backward compatibility.
2453
2454 @end table
2455
2456 @noindent
2457 Now that we know the key basics, we can carry on and explain how to
2458 encrypt and decrypt data.  In almost all cases the data is a random
2459 session key which is in turn used for the actual encryption of the real
2460 data.  There are 2 functions to do this:
2461
2462 @deftypefun gcry_error_t gcry_pk_encrypt (@w{gcry_sexp_t *@var{r_ciph},} @w{gcry_sexp_t @var{data},} @w{gcry_sexp_t @var{pkey}})
2463
2464 Obviously a public key must be provided for encryption.  It is
2465 expected as an appropriate S-expression (see above) in @var{pkey}.
2466 The data to be encrypted can either be in the simple old format, which
2467 is a very simple S-expression consisting only of one MPI, or it may be
2468 a more complex S-expression which also allows to specify flags for
2469 operation, like e.g. padding rules.
2470
2471 @noindent
2472 If you don't want to let Libgcrypt handle the padding, you must pass an
2473 appropriate MPI using this expression for @var{data}:
2474
2475 @example
2476 (data
2477   (flags raw)
2478   (value @var{mpi}))
2479 @end example
2480
2481 @noindent
2482 This has the same semantics as the old style MPI only way.  @var{MPI}
2483 is the actual data, already padded appropriate for your protocol.
2484 Most RSA based systems however use PKCS#1 padding and so you can use
2485 this S-expression for @var{data}:
2486
2487 @example
2488 (data
2489   (flags pkcs1)
2490   (value @var{block}))
2491 @end example
2492
2493 @noindent
2494 Here, the "flags" list has the "pkcs1" flag which let the function know
2495 that it should provide PKCS#1 block type 2 padding.  The actual data to
2496 be encrypted is passed as a string of octets in @var{block}.  The
2497 function checks that this data actually can be used with the given key,
2498 does the padding and encrypts it.
2499
2500 If the function could successfully perform the encryption, the return
2501 value will be 0 and a new S-expression with the encrypted result is
2502 allocated and assigned to the variable at the address of @var{r_ciph}.
2503 The caller is responsible to release this value using
2504 @code{gcry_sexp_release}.  In case of an error, an error code is
2505 returned and @var{r_ciph} will be set to @code{NULL}.
2506
2507 @noindent
2508 The returned S-expression has this format when used with RSA:
2509
2510 @example
2511 (enc-val
2512   (rsa
2513     (a @var{a-mpi})))
2514 @end example
2515
2516 @noindent
2517 Where @var{a-mpi} is an MPI with the result of the RSA operation.  When
2518 using the Elgamal algorithm, the return value will have this format:
2519
2520 @example
2521 (enc-val
2522   (elg
2523     (a @var{a-mpi})
2524     (b @var{b-mpi})))
2525 @end example
2526
2527 @noindent
2528 Where @var{a-mpi} and @var{b-mpi} are MPIs with the result of the
2529 Elgamal encryption operation.
2530 @end deftypefun
2531 @c end gcry_pk_encrypt
2532
2533 @deftypefun gcry_error_t gcry_pk_decrypt (@w{gcry_sexp_t *@var{r_plain},} @w{gcry_sexp_t @var{data},} @w{gcry_sexp_t @var{skey}})
2534
2535 Obviously a private key must be provided for decryption.  It is expected
2536 as an appropriate S-expression (see above) in @var{skey}.  The data to
2537 be decrypted must match the format of the result as returned by
2538 @code{gcry_pk_encrypt}, but should be enlarged with a @code{flags}
2539 element:
2540
2541 @example
2542 (enc-val
2543   (flags)
2544   (elg
2545     (a @var{a-mpi})
2546     (b @var{b-mpi})))
2547 @end example
2548
2549 @noindent
2550 This function does not remove padding from the data by default.  To
2551 let Libgcrypt remove padding, give a hint in `flags' telling which
2552 padding method was used when encrypting:
2553
2554 @example
2555 (flags @var{padding-method})
2556 @end example
2557
2558 @noindent
2559 Currently @var{padding-method} is either @code{pkcs1} for PKCS#1 block
2560 type 2 padding, or @code{oaep} for RSA-OAEP padding.
2561
2562 @noindent
2563 The function returns 0 on success or an error code.  The variable at the
2564 address of @var{r_plain} will be set to NULL on error or receive the
2565 decrypted value on success.  The format of @var{r_plain} is a
2566 simple S-expression part (i.e. not a valid one) with just one MPI if
2567 there was no @code{flags} element in @var{data}; if at least an empty
2568 @code{flags} is passed in @var{data}, the format is:
2569
2570 @example
2571 (value @var{plaintext})
2572 @end example
2573 @end deftypefun
2574 @c end gcry_pk_decrypt
2575
2576
2577 Another operation commonly performed using public key cryptography is
2578 signing data.  In some sense this is even more important than
2579 encryption because digital signatures are an important instrument for
2580 key management.  Libgcrypt supports digital signatures using
2581 2 functions, similar to the encryption functions:
2582
2583 @deftypefun gcry_error_t gcry_pk_sign (@w{gcry_sexp_t *@var{r_sig},} @w{gcry_sexp_t @var{data},} @w{gcry_sexp_t @var{skey}})
2584
2585 This function creates a digital signature for @var{data} using the
2586 private key @var{skey} and place it into the variable at the address of
2587 @var{r_sig}.  @var{data} may either be the simple old style S-expression
2588 with just one MPI or a modern and more versatile S-expression which
2589 allows to let Libgcrypt handle padding:
2590
2591 @example
2592  (data
2593   (flags pkcs1)
2594   (hash @var{hash-algo} @var{block}))
2595 @end example
2596
2597 @noindent
2598 This example requests to sign the data in @var{block} after applying
2599 PKCS#1 block type 1 style padding.  @var{hash-algo} is a string with the
2600 hash algorithm to be encoded into the signature, this may be any hash
2601 algorithm name as supported by Libgcrypt.  Most likely, this will be
2602 "sha256" or "sha1".  It is obvious that the length of @var{block} must
2603 match the size of that message digests; the function checks that this
2604 and other constraints are valid.
2605
2606 @noindent
2607 If PKCS#1 padding is not required (because the caller does already
2608 provide a padded value), either the old format or better the following
2609 format should be used:
2610
2611 @example
2612 (data
2613   (flags raw)
2614   (value @var{mpi}))
2615 @end example
2616
2617 @noindent
2618 Here, the data to be signed is directly given as an @var{MPI}.
2619
2620 @noindent
2621 For DSA the input data is expected in this format:
2622
2623 @example
2624 (data
2625   (flags raw)
2626   (value @var{mpi}))
2627 @end example
2628
2629 @noindent
2630 Here, the data to be signed is directly given as an @var{MPI}.  It is
2631 expect that this MPI is the the hash value.  For the standard DSA
2632 using a MPI is not a problem in regard to leading zeroes because the
2633 hash value is directly used as an MPI.  For better standard
2634 conformance it would be better to explicit use a memory string (like
2635 with pkcs1) but that is currently not supported.  However, for
2636 deterministic DSA as specified in RFC6979 this can't be used.  Instead
2637 the following input is expected.
2638
2639 @example
2640 (data
2641   (flags rfc6979)
2642   (hash @var{hash-algo} @var{block}))
2643 @end example
2644
2645 Note that the provided hash-algo is used for the internal HMAC; it
2646 should match the hash-algo used to create @var{block}.
2647
2648
2649 @noindent
2650 The signature is returned as a newly allocated S-expression in
2651 @var{r_sig} using this format for RSA:
2652
2653 @example
2654 (sig-val
2655   (rsa
2656     (s @var{s-mpi})))
2657 @end example
2658
2659 Where @var{s-mpi} is the result of the RSA sign operation.  For DSA the
2660 S-expression returned is:
2661
2662 @example
2663 (sig-val
2664   (dsa
2665     (r @var{r-mpi})
2666     (s @var{s-mpi})))
2667 @end example
2668
2669 Where @var{r-mpi} and @var{s-mpi} are the result of the DSA sign
2670 operation.
2671
2672 For Elgamal signing (which is slow, yields large numbers and probably
2673 is not as secure as the other algorithms), the same format is used
2674 with "elg" replacing "dsa"; for ECDSA signing, the same format is used
2675 with "ecdsa" replacing "dsa".
2676
2677 For the EdDSA algorithm (cf. Ed25515) the required input parameters are:
2678
2679 @example
2680 (data
2681   (flags eddsa)
2682   (hash-algo sha512)
2683   (value @var{message}))
2684 @end example
2685
2686 Note that the @var{message} may be of any length; hashing is part of
2687 the algorithm.  Using a large data block for @var{message} is not
2688 suggested; in that case the used protocol should better require that a
2689 hash of the message is used as input to the EdDSA algorithm.
2690
2691
2692 @end deftypefun
2693 @c end gcry_pk_sign
2694
2695 @noindent
2696 The operation most commonly used is definitely the verification of a
2697 signature.  Libgcrypt provides this function:
2698
2699 @deftypefun gcry_error_t gcry_pk_verify (@w{gcry_sexp_t @var{sig}}, @w{gcry_sexp_t @var{data}}, @w{gcry_sexp_t @var{pkey}})
2700
2701 This is used to check whether the signature @var{sig} matches the
2702 @var{data}.  The public key @var{pkey} must be provided to perform this
2703 verification.  This function is similar in its parameters to
2704 @code{gcry_pk_sign} with the exceptions that the public key is used
2705 instead of the private key and that no signature is created but a
2706 signature, in a format as created by @code{gcry_pk_sign}, is passed to
2707 the function in @var{sig}.
2708
2709 @noindent
2710 The result is 0 for success (i.e. the data matches the signature), or an
2711 error code where the most relevant code is @code{GCRY_ERR_BAD_SIGNATURE}
2712 to indicate that the signature does not match the provided data.
2713
2714 @end deftypefun
2715 @c end gcry_pk_verify
2716
2717 @node General public-key related Functions
2718 @section General public-key related Functions
2719
2720 @noindent
2721 A couple of utility functions are available to retrieve the length of
2722 the key, map algorithm identifiers and perform sanity checks:
2723
2724 @deftypefun {const char *} gcry_pk_algo_name (int @var{algo})
2725
2726 Map the public key algorithm id @var{algo} to a string representation of
2727 the algorithm name.  For unknown algorithms this functions returns the
2728 string @code{"?"}.  This function should not be used to test for the
2729 availability of an algorithm.
2730 @end deftypefun
2731
2732 @deftypefun int gcry_pk_map_name (const char *@var{name})
2733
2734 Map the algorithm @var{name} to a public key algorithm Id.  Returns 0 if
2735 the algorithm name is not known.
2736 @end deftypefun
2737
2738 @deftypefun int gcry_pk_test_algo (int @var{algo})
2739
2740 Return 0 if the public key algorithm @var{algo} is available for use.
2741 Note that this is implemented as a macro.
2742 @end deftypefun
2743
2744
2745 @deftypefun {unsigned int} gcry_pk_get_nbits (gcry_sexp_t @var{key})
2746
2747 Return what is commonly referred as the key length for the given
2748 public or private in @var{key}.
2749 @end deftypefun
2750
2751 @deftypefun {unsigned char *} gcry_pk_get_keygrip (@w{gcry_sexp_t @var{key}}, @w{unsigned char *@var{array}})
2752
2753 Return the so called "keygrip" which is the SHA-1 hash of the public key
2754 parameters expressed in a way depended on the algorithm.  @var{array}
2755 must either provide space for 20 bytes or be @code{NULL}. In the latter
2756 case a newly allocated array of that size is returned.  On success a
2757 pointer to the newly allocated space or to @var{array} is returned.
2758 @code{NULL} is returned to indicate an error which is most likely an
2759 unknown algorithm or one where a "keygrip" has not yet been defined.
2760 The function accepts public or secret keys in @var{key}.
2761 @end deftypefun
2762
2763 @deftypefun gcry_error_t gcry_pk_testkey (gcry_sexp_t @var{key})
2764
2765 Return zero if the private key @var{key} is `sane', an error code otherwise.
2766 Note that it is not possible to check the `saneness' of a public key.
2767
2768 @end deftypefun
2769
2770
2771 @deftypefun gcry_error_t gcry_pk_algo_info (@w{int @var{algo}}, @w{int @var{what}}, @w{void *@var{buffer}}, @w{size_t *@var{nbytes}})
2772
2773 Depending on the value of @var{what} return various information about
2774 the public key algorithm with the id @var{algo}.  Note that the
2775 function returns @code{-1} on error and the actual error code must be
2776 retrieved using the function @code{gcry_errno}.  The currently defined
2777 values for @var{what} are:
2778
2779 @table @code
2780 @item GCRYCTL_TEST_ALGO:
2781 Return 0 if the specified algorithm is available for use.
2782 @var{buffer} must be @code{NULL}, @var{nbytes} may be passed as
2783 @code{NULL} or point to a variable with the required usage of the
2784 algorithm. This may be 0 for "don't care" or the bit-wise OR of these
2785 flags:
2786
2787 @table @code
2788 @item GCRY_PK_USAGE_SIGN
2789 Algorithm is usable for signing.
2790 @item GCRY_PK_USAGE_ENCR
2791 Algorithm is usable for encryption.
2792 @end table
2793
2794 Unless you need to test for the allowed usage, it is in general better
2795 to use the macro gcry_pk_test_algo instead.
2796
2797 @item GCRYCTL_GET_ALGO_USAGE:
2798 Return the usage flags for the given algorithm.  An invalid algorithm
2799 return 0.  Disabled algorithms are ignored here because we
2800 want to know whether the algorithm is at all capable of a certain usage.
2801
2802 @item GCRYCTL_GET_ALGO_NPKEY
2803 Return the number of elements the public key for algorithm @var{algo}
2804 consist of.  Return 0 for an unknown algorithm.
2805
2806 @item GCRYCTL_GET_ALGO_NSKEY
2807 Return the number of elements the private key for algorithm @var{algo}
2808 consist of.  Note that this value is always larger than that of the
2809 public key.  Return 0 for an unknown algorithm.
2810
2811 @item GCRYCTL_GET_ALGO_NSIGN
2812 Return the number of elements a signature created with the algorithm
2813 @var{algo} consists of.  Return 0 for an unknown algorithm or for an
2814 algorithm not capable of creating signatures.
2815
2816 @item GCRYCTL_GET_ALGO_NENC
2817 Return the number of elements a encrypted message created with the algorithm
2818 @var{algo} consists of.  Return 0 for an unknown algorithm or for an
2819 algorithm not capable of encryption.
2820 @end table
2821
2822 @noindent
2823 Please note that parameters not required should be passed as @code{NULL}.
2824 @end deftypefun
2825 @c end gcry_pk_algo_info
2826
2827
2828 @deftypefun gcry_error_t gcry_pk_ctl (@w{int @var{cmd}}, @w{void *@var{buffer}}, @w{size_t @var{buflen}})
2829
2830 This is a general purpose function to perform certain control
2831 operations.  @var{cmd} controls what is to be done. The return value is
2832 0 for success or an error code.  Currently supported values for
2833 @var{cmd} are:
2834
2835 @table @code
2836 @item GCRYCTL_DISABLE_ALGO
2837 Disable the algorithm given as an algorithm id in @var{buffer}.
2838 @var{buffer} must point to an @code{int} variable with the algorithm
2839 id and @var{buflen} must have the value @code{sizeof (int)}.  This
2840 function is not thread safe and should thus be used before any other
2841 threads are started.
2842
2843 @end table
2844 @end deftypefun
2845 @c end gcry_pk_ctl
2846
2847 @noindent
2848 Libgcrypt also provides a function to generate public key
2849 pairs:
2850
2851 @deftypefun gcry_error_t gcry_pk_genkey (@w{gcry_sexp_t *@var{r_key}}, @w{gcry_sexp_t @var{parms}})
2852
2853 This function create a new public key pair using information given in
2854 the S-expression @var{parms} and stores the private and the public key
2855 in one new S-expression at the address given by @var{r_key}.  In case of
2856 an error, @var{r_key} is set to @code{NULL}.  The return code is 0 for
2857 success or an error code otherwise.
2858
2859 @noindent
2860 Here is an example for @var{parms} to create an 2048 bit RSA key:
2861
2862 @example
2863 (genkey
2864   (rsa
2865     (nbits 4:2048)))
2866 @end example
2867
2868 @noindent
2869 To create an Elgamal key, substitute "elg" for "rsa" and to create a DSA
2870 key use "dsa".  Valid ranges for the key length depend on the
2871 algorithms; all commonly used key lengths are supported.  Currently
2872 supported parameters are:
2873
2874 @table @code
2875 @item nbits
2876 This is always required to specify the length of the key.  The
2877 argument is a string with a number in C-notation.  The value should be
2878 a multiple of 8.  Note that the S-expression syntax requires that a
2879 number is prefixed with its string length; thus the @code{4:} in the
2880 above example.
2881
2882 @item curve @var{name}
2883 For ECC a named curve may be used instead of giving the number of
2884 requested bits.  This allows to request a specific curve to override a
2885 default selection Libgcrypt would have taken if @code{nbits} has been
2886 given.  The available names are listed with the description of the ECC
2887 public key parameters.
2888
2889 @item rsa-use-e @var{value}
2890 This is only used with RSA to give a hint for the public exponent. The
2891 @var{value} will be used as a base to test for a usable exponent. Some
2892 values are special:
2893
2894 @table @samp
2895 @item 0
2896 Use a secure and fast value.  This is currently the number 41.
2897 @item 1
2898 Use a value as required by some crypto policies.  This is currently
2899 the number 65537.
2900 @item 2
2901 Reserved
2902 @item > 2
2903 Use the given value.
2904 @end table
2905
2906 @noindent
2907 If this parameter is not used, Libgcrypt uses for historic reasons
2908 65537.  Note that the value must fit into a 32 bit unsigned variable
2909 and that the usual C prefixes are considered (e.g. 017 gives 15).
2910
2911
2912 @item qbits @var{n}
2913 This is only meanigful for DSA keys.  If it is given the DSA key is
2914 generated with a Q parameyer of size @var{n} bits.  If it is not given
2915 or zero Q is deduced from NBITS in this way:
2916 @table @samp
2917 @item 512 <= N <= 1024
2918 Q = 160
2919 @item N = 2048
2920 Q = 224
2921 @item N = 3072
2922 Q = 256
2923 @item N = 7680
2924 Q = 384
2925 @item N = 15360
2926 Q = 512
2927 @end table
2928 Note that in this case only the values for N, as given in the table,
2929 are allowed.  When specifying Q all values of N in the range 512 to
2930 15680 are valid as long as they are multiples of 8.
2931
2932 @item domain @var{list}
2933 This is only meaningful for DLP algorithms.  If specified keys are
2934 generated with domain parameters taken from this list.  The exact
2935 format of this parameter depends on the actual algorithm.  It is
2936 currently only implemented for DSA using this format:
2937
2938 @example
2939 (genkey
2940   (dsa
2941     (domain
2942       (p @var{p-mpi})
2943       (q @var{q-mpi})
2944       (g @var{q-mpi}))))
2945 @end example
2946
2947 @code{nbits} and @code{qbits} may not be specified because they are
2948 derived from the domain parameters.
2949
2950 @item derive-parms @var{list}
2951 This is currently only implemented for RSA and DSA keys.  It is not
2952 allowed to use this together with a @code{domain} specification.  If
2953 given, it is used to derive the keys using the given parameters.
2954
2955 If given for an RSA key the X9.31 key generation algorithm is used
2956 even if libgcrypt is not in FIPS mode.  If given for a DSA key, the
2957 FIPS 186 algorithm is used even if libgcrypt is not in FIPS mode.
2958
2959 @example
2960 (genkey
2961   (rsa
2962     (nbits 4:1024)
2963     (rsa-use-e 1:3)
2964     (derive-parms
2965       (Xp1 #1A1916DDB29B4EB7EB6732E128#)
2966       (Xp2 #192E8AAC41C576C822D93EA433#)
2967       (Xp  #D8CD81F035EC57EFE822955149D3BFF70C53520D
2968             769D6D76646C7A792E16EBD89FE6FC5B605A6493
2969             39DFC925A86A4C6D150B71B9EEA02D68885F5009
2970             B98BD984#)
2971       (Xq1 #1A5CF72EE770DE50CB09ACCEA9#)
2972       (Xq2 #134E4CAA16D2350A21D775C404#)
2973       (Xq  #CC1092495D867E64065DEE3E7955F2EBC7D47A2D
2974             7C9953388F97DDDC3E1CA19C35CA659EDC2FC325
2975             6D29C2627479C086A699A49C4C9CEE7EF7BD1B34
2976             321DE34A#))))
2977 @end example
2978
2979 @example
2980 (genkey
2981   (dsa
2982     (nbits 4:1024)
2983     (derive-parms
2984       (seed @var{seed-mpi}))))
2985 @end example
2986
2987
2988 @item flags @var{flaglist}
2989 This is preferred way to define flags.  @var{flaglist} may contain any
2990 number of flags.  See above for a specification of these flags.
2991
2992 Here is an example on how to create a key using curve Ed25519 with the
2993 ECDSA signature algorithm.  Note that the use of ECDSA with that curve
2994 is in general not recommended.
2995 @example
2996 (genkey
2997   (ecc
2998     (flags transient-key)))
2999 @end example
3000
3001 @item transient-key
3002 @itemx use-x931
3003 @itemx use-fips186
3004 @itemx use-fips186-2
3005 These are deprecated ways to set a flag with that name; see above for
3006 a description of each flag.
3007
3008
3009 @end table
3010 @c end table of parameters
3011
3012 @noindent
3013 The key pair is returned in a format depending on the algorithm.  Both
3014 private and public keys are returned in one container and may be
3015 accompanied by some miscellaneous information.
3016
3017 @noindent
3018 Here are two examples; the first for Elgamal and the second for
3019 elliptic curve key generation:
3020
3021 @example
3022 (key-data
3023   (public-key
3024     (elg
3025       (p @var{p-mpi})
3026       (g @var{g-mpi})
3027       (y @var{y-mpi})))
3028   (private-key
3029     (elg
3030       (p @var{p-mpi})
3031       (g @var{g-mpi})
3032       (y @var{y-mpi})
3033       (x @var{x-mpi})))
3034   (misc-key-info
3035     (pm1-factors @var{n1 n2 ... nn}))
3036 @end example
3037
3038 @example
3039 (key-data
3040   (public-key
3041     (ecc
3042       (curve Ed25519)
3043       (flags eddsa)
3044       (q @var{q-value})))
3045   (private-key
3046     (ecc
3047       (curve Ed25519)
3048       (flags eddsa)
3049       (q @var{q-value})
3050       (d @var{d-value}))))
3051 @end example
3052
3053 @noindent
3054 As you can see, some of the information is duplicated, but this
3055 provides an easy way to extract either the public or the private key.
3056 Note that the order of the elements is not defined, e.g. the private
3057 key may be stored before the public key. @var{n1 n2 ... nn} is a list
3058 of prime numbers used to composite @var{p-mpi}; this is in general not
3059 a very useful information and only available if the key generation
3060 algorithm provides them.
3061 @end deftypefun
3062 @c end gcry_pk_genkey
3063
3064
3065 @noindent
3066 Future versions of Libgcrypt will have extended versions of the public
3067 key interfaced which will take an additional context to allow for
3068 pre-computations, special operations, and other optimization.  As a
3069 first step a new function is introduced to help using the ECC
3070 algorithms in new ways:
3071
3072 @deftypefun gcry_error_t gcry_pubkey_get_sexp (@w{gcry_sexp_t *@var{r_sexp}}, @
3073  @w{int @var{mode}}, @w{gcry_ctx_t @var{ctx}})
3074
3075 Return an S-expression representing the context @var{ctx}.  Depending
3076 on the state of that context, the S-expression may either be a public
3077 key, a private key or any other object used with public key
3078 operations.  On success 0 is returned and a new S-expression is stored
3079 at @var{r_sexp}; on error an error code is returned and NULL is stored
3080 at @var{r_sexp}.  @var{mode} must be one of:
3081
3082 @table @code
3083 @item 0
3084 Decide what to return depending on the context.  For example if the
3085 private key parameter is available a private key is returned, if not a
3086 public key is returned.
3087
3088 @item GCRY_PK_GET_PUBKEY
3089 Return the public key even if the context has the private key
3090 parameter.
3091
3092 @item GCRY_PK_GET_SECKEY
3093 Return the private key or the error @code{GPG_ERR_NO_SECKEY} if it is
3094 not possible.
3095 @end table
3096
3097 As of now this function supports only certain ECC operations because a
3098 context object is right now only defined for ECC.  Over time this
3099 function will be extended to cover more algorithms.
3100
3101 @end deftypefun
3102 @c end gcry_pubkey_get_sexp
3103
3104
3105
3106
3107
3108 @c **********************************************************
3109 @c *******************  Hash Functions  *********************
3110 @c **********************************************************
3111 @node Hashing
3112 @chapter Hashing
3113
3114 Libgcrypt provides an easy and consistent to use interface for hashing.
3115 Hashing is buffered and several hash algorithms can be updated at once.
3116 It is possible to compute a HMAC using the same routines.  The
3117 programming model follows an open/process/close paradigm and is in that
3118 similar to other building blocks provided by Libgcrypt.
3119
3120 For convenience reasons, a few cyclic redundancy check value operations
3121 are also supported.
3122
3123 @menu
3124 * Available hash algorithms::   List of hash algorithms supported by the library.
3125 * Working with hash algorithms::  List of functions related to hashing.
3126 @end menu
3127
3128 @node Available hash algorithms
3129 @section Available hash algorithms
3130
3131 @c begin table of hash algorithms
3132 @cindex SHA-1
3133 @cindex SHA-224, SHA-256, SHA-384, SHA-512
3134 @cindex SHA3-224, SHA3-256, SHA3-384, SHA3-512, SHAKE128, SHAKE256
3135 @cindex RIPE-MD-160
3136 @cindex MD2, MD4, MD5
3137 @cindex TIGER, TIGER1, TIGER2
3138 @cindex HAVAL
3139 @cindex Whirlpool
3140 @cindex BLAKE2b-512, BLAKE2b-384, BLAKE2b-256, BLAKE2b-160
3141 @cindex BLAKE2s-256, BLAKE2s-224, BLAKE2s-160, BLAKE2s-128
3142 @cindex CRC32
3143 @table @code
3144 @item GCRY_MD_NONE
3145 This is not a real algorithm but used by some functions as an error
3146 return value.  This constant is guaranteed to have the value @code{0}.
3147
3148 @item GCRY_MD_SHA1
3149 This is the SHA-1 algorithm which yields a message digest of 20 bytes.
3150 Note that SHA-1 begins to show some weaknesses and it is suggested to
3151 fade out its use if strong cryptographic properties are required.
3152
3153 @item GCRY_MD_RMD160
3154 This is the 160 bit version of the RIPE message digest (RIPE-MD-160).
3155 Like SHA-1 it also yields a digest of 20 bytes.  This algorithm share a
3156 lot of design properties with SHA-1 and thus it is advisable not to use
3157 it for new protocols.
3158
3159 @item GCRY_MD_MD5
3160 This is the well known MD5 algorithm, which yields a message digest of
3161 16 bytes.  Note that the MD5 algorithm has severe weaknesses, for
3162 example it is easy to compute two messages yielding the same hash
3163 (collision attack).  The use of this algorithm is only justified for
3164 non-cryptographic application.
3165
3166
3167 @item GCRY_MD_MD4
3168 This is the MD4 algorithm, which yields a message digest of 16 bytes.
3169 This algorithm has severe weaknesses and should not be used.
3170
3171 @item GCRY_MD_MD2
3172 This is an reserved identifier for MD-2; there is no implementation yet.
3173 This algorithm has severe weaknesses and should not be used.
3174
3175 @item GCRY_MD_TIGER
3176 This is the TIGER/192 algorithm which yields a message digest of 24
3177 bytes.  Actually this is a variant of TIGER with a different output
3178 print order as used by GnuPG up to version 1.3.2.
3179
3180 @item GCRY_MD_TIGER1
3181 This is the TIGER variant as used by the NESSIE project.  It uses the
3182 most commonly used output print order.
3183
3184 @item GCRY_MD_TIGER2
3185 This is another variant of TIGER with a different padding scheme.
3186
3187
3188 @item GCRY_MD_HAVAL
3189 This is an reserved value for the HAVAL algorithm with 5 passes and 160
3190 bit. It yields a message digest of 20 bytes.  Note that there is no
3191 implementation yet available.
3192
3193 @item GCRY_MD_SHA224
3194 This is the SHA-224 algorithm which yields a message digest of 28 bytes.
3195 See Change Notice 1 for FIPS 180-2 for the specification.
3196
3197 @item GCRY_MD_SHA256
3198 This is the SHA-256 algorithm which yields a message digest of 32 bytes.
3199 See FIPS 180-2 for the specification.
3200
3201 @item GCRY_MD_SHA384
3202 This is the SHA-384 algorithm which yields a message digest of 48 bytes.
3203 See FIPS 180-2 for the specification.
3204
3205 @item GCRY_MD_SHA512
3206 This is the SHA-384 algorithm which yields a message digest of 64 bytes.
3207 See FIPS 180-2 for the specification.
3208
3209 @item GCRY_MD_SHA3_224
3210 This is the SHA3-224 algorithm which yields a message digest of 28 bytes.
3211 See FIPS 202 for the specification.
3212
3213 @item GCRY_MD_SHA3_256
3214 This is the SHA3-256 algorithm which yields a message digest of 32 bytes.
3215 See FIPS 202 for the specification.
3216
3217 @item GCRY_MD_SHA3_384
3218 This is the SHA3-384 algorithm which yields a message digest of 48 bytes.
3219 See FIPS 202 for the specification.
3220
3221 @item GCRY_MD_SHA3_512
3222 This is the SHA3-384 algorithm which yields a message digest of 64 bytes.
3223 See FIPS 202 for the specification.
3224
3225 @item GCRY_MD_SHAKE128
3226 This is the SHAKE128 extendable-output function (XOF) algorithm with 128 bit
3227 security strength.
3228 See FIPS 202 for the specification.
3229
3230 @item GCRY_MD_SHAKE256
3231 This is the SHAKE256 extendable-output function (XOF) algorithm with 256 bit
3232 security strength.
3233 See FIPS 202 for the specification.
3234
3235 @item GCRY_MD_CRC32
3236 This is the ISO 3309 and ITU-T V.42 cyclic redundancy check.  It yields
3237 an output of 4 bytes.  Note that this is not a hash algorithm in the
3238 cryptographic sense.
3239
3240 @item GCRY_MD_CRC32_RFC1510
3241 This is the above cyclic redundancy check function, as modified by RFC
3242 1510.  It yields an output of 4 bytes.  Note that this is not a hash
3243 algorithm in the cryptographic sense.
3244
3245 @item GCRY_MD_CRC24_RFC2440
3246 This is the OpenPGP cyclic redundancy check function.  It yields an
3247 output of 3 bytes.  Note that this is not a hash algorithm in the
3248 cryptographic sense.
3249
3250 @item GCRY_MD_WHIRLPOOL
3251 This is the Whirlpool algorithm which yields a message digest of 64
3252 bytes.
3253
3254 @item GCRY_MD_GOSTR3411_94
3255 This is the hash algorithm described in GOST R 34.11-94 which yields a
3256 message digest of 32 bytes.
3257
3258 @item GCRY_MD_STRIBOG256
3259 This is the 256-bit version of hash algorithm described in GOST R 34.11-2012
3260 which yields a message digest of 32 bytes.
3261
3262 @item GCRY_MD_STRIBOG512
3263 This is the 512-bit version of hash algorithm described in GOST R 34.11-2012
3264 which yields a message digest of 64 bytes.
3265
3266 @item GCRY_MD_BLAKE2B_512
3267 This is the BLAKE2b-512 algorithm which yields a message digest of 64 bytes.
3268 See RFC 7693 for the specification.
3269
3270 @item GCRY_MD_BLAKE2B_384
3271 This is the BLAKE2b-384 algorithm which yields a message digest of 48 bytes.
3272 See RFC 7693 for the specification.
3273
3274 @item GCRY_MD_BLAKE2B_256
3275 This is the BLAKE2b-256 algorithm which yields a message digest of 32 bytes.
3276 See RFC 7693 for the specification.
3277
3278 @item GCRY_MD_BLAKE2B_160
3279 This is the BLAKE2b-160 algorithm which yields a message digest of 20 bytes.
3280 See RFC 7693 for the specification.
3281
3282 @item GCRY_MD_BLAKE2S_256
3283 This is the BLAKE2s-256 algorithm which yields a message digest of 32 bytes.
3284 See RFC 7693 for the specification.
3285
3286 @item GCRY_MD_BLAKE2S_224
3287 This is the BLAKE2s-224 algorithm which yields a message digest of 28 bytes.
3288 See RFC 7693 for the specification.
3289
3290 @item GCRY_MD_BLAKE2S_160
3291 This is the BLAKE2s-160 algorithm which yields a message digest of 20 bytes.
3292 See RFC 7693 for the specification.
3293
3294 @item GCRY_MD_BLAKE2S_128
3295 This is the BLAKE2s-128 algorithm which yields a message digest of 16 bytes.
3296 See RFC 7693 for the specification.
3297
3298 @end table
3299 @c end table of hash algorithms
3300
3301 @node Working with hash algorithms
3302 @section Working with hash algorithms
3303
3304 To use most of these function it is necessary to create a context;
3305 this is done using:
3306
3307 @deftypefun gcry_error_t gcry_md_open (gcry_md_hd_t *@var{hd}, int @var{algo}, unsigned int @var{flags})
3308
3309 Create a message digest object for algorithm @var{algo}.  @var{flags}
3310 may be given as an bitwise OR of constants described below.  @var{algo}
3311 may be given as @code{0} if the algorithms to use are later set using
3312 @code{gcry_md_enable}. @var{hd} is guaranteed to either receive a valid
3313 handle or NULL.
3314
3315 For a list of supported algorithms, see @ref{Available hash
3316 algorithms}.
3317
3318 The flags allowed for @var{mode} are:
3319
3320 @c begin table of hash flags
3321 @table @code
3322 @item GCRY_MD_FLAG_SECURE
3323 Allocate all buffers and the resulting digest in "secure memory".  Use
3324 this is the hashed data is highly confidential.
3325
3326 @item GCRY_MD_FLAG_HMAC
3327 @cindex HMAC
3328 Turn the algorithm into a HMAC message authentication algorithm.  This
3329 only works if just one algorithm is enabled for the handle and that
3330 algorithm is not an extendable-output function.  Note that the function
3331 @code{gcry_md_setkey} must be used to set the MAC key.  The size of the
3332 MAC is equal to the message digest of the underlying hash algorithm.
3333 If you want CBC message authentication codes based on a cipher,
3334 see @ref{Working with cipher handles}.
3335
3336 @item GCRY_MD_FLAG_BUGEMU1
3337 @cindex bug emulation
3338 Versions of Libgcrypt before 1.6.0 had a bug in the Whirlpool code
3339 which led to a wrong result for certain input sizes and write
3340 patterns.  Using this flag emulates that bug.  This may for example be
3341 useful for applications which use Whirlpool as part of their key
3342 generation.  It is strongly suggested to use this flag only if really
3343 needed and if possible to the data should be re-processed using the
3344 regular Whirlpool algorithm.
3345
3346 Note that this flag works for the entire hash context.  If needed
3347 arises it may be used to enable bug emulation for other hash
3348 algorithms.  Thus you should not use this flag for a multi-algorithm
3349 hash context.
3350
3351
3352 @end table
3353 @c begin table of hash flags
3354
3355 You may use the function @code{gcry_md_is_enabled} to later check
3356 whether an algorithm has been enabled.
3357
3358 @end deftypefun
3359 @c end function gcry_md_open
3360
3361 If you want to calculate several hash algorithms at the same time, you
3362 have to use the following function right after the @code{gcry_md_open}:
3363
3364 @deftypefun gcry_error_t gcry_md_enable (gcry_md_hd_t @var{h}, int @var{algo})
3365
3366 Add the message digest algorithm @var{algo} to the digest object
3367 described by handle @var{h}.  Duplicated enabling of algorithms is
3368 detected and ignored.
3369 @end deftypefun
3370
3371 If the flag @code{GCRY_MD_FLAG_HMAC} was used, the key for the MAC must
3372 be set using the function:
3373
3374 @deftypefun gcry_error_t gcry_md_setkey (gcry_md_hd_t @var{h}, const void *@var{key}, size_t @var{keylen})
3375
3376 For use with the HMAC feature or BLAKE2 keyed hash, set the MAC key to
3377 the value of @var{key} of length @var{keylen} bytes.  For HMAC, there
3378 is no restriction on the length of the key.  For keyed BLAKE2b hash,
3379 length of the key must be 64 bytes or less.  For keyed BLAKE2s hash,
3380 length of the key must be 32 bytes or less.
3381
3382 @end deftypefun
3383
3384
3385 After you are done with the hash calculation, you should release the
3386 resources by using:
3387
3388 @deftypefun void gcry_md_close (gcry_md_hd_t @var{h})
3389
3390 Release all resources of hash context @var{h}.  @var{h} should not be
3391 used after a call to this function.  A @code{NULL} passed as @var{h} is
3392 ignored.  The function also zeroises all sensitive information
3393 associated with this handle.
3394
3395
3396 @end deftypefun
3397
3398 Often you have to do several hash operations using the same algorithm.
3399 To avoid the overhead of creating and releasing context, a reset function
3400 is provided:
3401
3402 @deftypefun void gcry_md_reset (gcry_md_hd_t @var{h})
3403
3404 Reset the current context to its initial state.  This is effectively
3405 identical to a close followed by an open and enabling all currently
3406 active algorithms.
3407 @end deftypefun
3408
3409
3410 Often it is necessary to start hashing some data and then continue to
3411 hash different data.  To avoid hashing the same data several times (which
3412 might not even be possible if the data is received from a pipe), a
3413 snapshot of the current hash context can be taken and turned into a new
3414 context:
3415
3416 @deftypefun gcry_error_t gcry_md_copy (gcry_md_hd_t *@var{handle_dst}, gcry_md_hd_t @var{handle_src})
3417
3418 Create a new digest object as an exact copy of the object described by
3419 handle @var{handle_src} and store it in @var{handle_dst}.  The context
3420 is not reset and you can continue to hash data using this context and
3421 independently using the original context.
3422 @end deftypefun
3423
3424
3425 Now that we have prepared everything to calculate hashes, it is time to
3426 see how it is actually done.  There are two ways for this, one to
3427 update the hash with a block of memory and one macro to update the hash
3428 by just one character.  Both methods can be used on the same hash context.
3429
3430 @deftypefun void gcry_md_write (gcry_md_hd_t @var{h}, const void *@var{buffer}, size_t @var{length})
3431
3432 Pass @var{length} bytes of the data in @var{buffer} to the digest object
3433 with handle @var{h} to update the digest values. This
3434 function should be used for large blocks of data.  If this function is
3435 used after the context has been finalized, it will keep on pushing
3436 the data through the algorithm specific transform function and change
3437 the context; however the results are not meaningful and this feature
3438 is only available to mitigate timing attacks.
3439 @end deftypefun
3440
3441 @deftypefun void gcry_md_putc (gcry_md_hd_t @var{h}, int @var{c})
3442
3443 Pass the byte in @var{c} to the digest object with handle @var{h} to
3444 update the digest value.  This is an efficient function, implemented as
3445 a macro to buffer the data before an actual update.
3446 @end deftypefun
3447
3448 The semantics of the hash functions do not provide for reading out intermediate
3449 message digests because the calculation must be finalized first.  This
3450 finalization may for example include the number of bytes hashed in the
3451 message digest or some padding.
3452
3453 @deftypefun void gcry_md_final (gcry_md_hd_t @var{h})
3454
3455 Finalize the message digest calculation.  This is not really needed
3456 because @code{gcry_md_read} and @code{gcry_md_extract} do this implicitly.
3457 After this has been done no further updates (by means of @code{gcry_md_write}
3458 or @code{gcry_md_putc} should be done; However, to mitigate timing
3459 attacks it is sometimes useful to keep on updating the context after
3460 having stored away the actual digest.  Only the first call to this function
3461 has an effect. It is implemented as a macro.
3462 @end deftypefun
3463
3464 The way to read out the calculated message digest is by using the
3465 function:
3466
3467 @deftypefun {unsigned char *} gcry_md_read (gcry_md_hd_t @var{h}, int @var{algo})
3468
3469 @code{gcry_md_read} returns the message digest after finalizing the
3470 calculation.  This function may be used as often as required but it will
3471 always return the same value for one handle.  The returned message digest
3472 is allocated within the message context and therefore valid until the
3473 handle is released or reset-ed (using @code{gcry_md_close} or
3474 @code{gcry_md_reset} or it has been updated as a mitigation measure
3475 against timing attacks.  @var{algo} may be given as 0 to return the only
3476 enabled message digest or it may specify one of the enabled algorithms.
3477 The function does return @code{NULL} if the requested algorithm has not
3478 been enabled.
3479 @end deftypefun
3480
3481 The way to read output of extendable-output function is by using the
3482 function:
3483
3484 @deftypefun gpg_err_code_t gcry_md_extract (gcry_md_hd_t @var{h}, @
3485   int @var{algo}, void *@var{buffer}, size_t @var{length})
3486
3487 @code{gcry_mac_read} returns output from extendable-output function.
3488 This function may be used as often as required to generate more output
3489 byte stream from the algorithm.  Function extracts the new output bytes
3490 to @var{buffer} of the length @var{length}.  Buffer will be fully
3491 populated with new output.  @var{algo} may be given as 0 to return the only
3492 enabled message digest or it may specify one of the enabled algorithms.
3493 The function does return non-zero value if the requested algorithm has not
3494 been enabled.
3495 @end deftypefun
3496
3497 Because it is often necessary to get the message digest of blocks of
3498 memory, two fast convenience function are available for this task:
3499
3500 @deftypefun gpg_err_code_t gcry_md_hash_buffers ( @
3501   @w{int @var{algo}}, @w{unsigned int @var{flags}}, @
3502   @w{void *@var{digest}}, @
3503   @w{const gcry_buffer_t *@var{iov}}, @w{int @var{iovcnt}} )
3504
3505 @code{gcry_md_hash_buffers} is a shortcut function to calculate a
3506 message digest from several buffers.  This function does not require a
3507 context and immediately returns the message digest of the data
3508 described by @var{iov} and @var{iovcnt}.  @var{digest} must be
3509 allocated by the caller, large enough to hold the message digest
3510 yielded by the the specified algorithm @var{algo}.  This required size
3511 may be obtained by using the function @code{gcry_md_get_algo_dlen}.
3512
3513 @var{iov} is an array of buffer descriptions with @var{iovcnt} items.
3514 The caller should zero out the structures in this array and for each
3515 array item set the fields @code{.data} to the address of the data to
3516 be hashed, @code{.len} to number of bytes to be hashed.  If @var{.off}
3517 is also set, the data is taken starting at @var{.off} bytes from the
3518 begin of the buffer.  The field @code{.size} is not used.
3519
3520 The only supported flag value for @var{flags} is
3521 @var{GCRY_MD_FLAG_HMAC} which turns this function into a HMAC
3522 function; the first item in @var{iov} is then used as the key.
3523
3524 On success the function returns 0 and stores the resulting hash or MAC
3525 at @var{digest}.
3526 @end deftypefun
3527
3528 @deftypefun void gcry_md_hash_buffer (int @var{algo}, void *@var{digest}, const void *@var{buffer}, size_t @var{length});
3529
3530 @code{gcry_md_hash_buffer} is a shortcut function to calculate a message
3531 digest of a buffer.  This function does not require a context and
3532 immediately returns the message digest of the @var{length} bytes at
3533 @var{buffer}.  @var{digest} must be allocated by the caller, large
3534 enough to hold the message digest yielded by the the specified algorithm
3535 @var{algo}.  This required size may be obtained by using the function
3536 @code{gcry_md_get_algo_dlen}.
3537
3538 Note that in contrast to @code{gcry_md_hash_buffers} this function
3539 will abort the process if an unavailable algorithm is used.
3540 @end deftypefun
3541
3542 @c ***********************************
3543 @c ***** MD info functions ***********
3544 @c ***********************************
3545
3546 Hash algorithms are identified by internal algorithm numbers (see
3547 @code{gcry_md_open} for a list).  However, in most applications they are
3548 used by names, so two functions are available to map between string
3549 representations and hash algorithm identifiers.
3550
3551 @deftypefun {const char *} gcry_md_algo_name (int @var{algo})
3552
3553 Map the digest algorithm id @var{algo} to a string representation of the
3554 algorithm name.  For unknown algorithms this function returns the
3555 string @code{"?"}.  This function should not be used to test for the
3556 availability of an algorithm.
3557 @end deftypefun
3558
3559 @deftypefun int gcry_md_map_name (const char *@var{name})
3560
3561 Map the algorithm with @var{name} to a digest algorithm identifier.
3562 Returns 0 if the algorithm name is not known.  Names representing
3563 @acronym{ASN.1} object identifiers are recognized if the @acronym{IETF}
3564 dotted format is used and the OID is prefixed with either "@code{oid.}"
3565 or "@code{OID.}".  For a list of supported OIDs, see the source code at
3566 @file{cipher/md.c}. This function should not be used to test for the
3567 availability of an algorithm.
3568 @end deftypefun
3569
3570 @deftypefun gcry_error_t gcry_md_get_asnoid (int @var{algo}, void *@var{buffer}, size_t *@var{length})
3571
3572 Return an DER encoded ASN.1 OID for the algorithm @var{algo} in the
3573 user allocated @var{buffer}. @var{length} must point to variable with
3574 the available size of @var{buffer} and receives after return the
3575 actual size of the returned OID.  The returned error code may be
3576 @code{GPG_ERR_TOO_SHORT} if the provided buffer is to short to receive
3577 the OID; it is possible to call the function with @code{NULL} for
3578 @var{buffer} to have it only return the required size.  The function
3579 returns 0 on success.
3580
3581 @end deftypefun
3582
3583
3584 To test whether an algorithm is actually available for use, the
3585 following macro should be used:
3586
3587 @deftypefun gcry_error_t gcry_md_test_algo (int @var{algo})
3588
3589 The macro returns 0 if the algorithm @var{algo} is available for use.
3590 @end deftypefun
3591
3592 If the length of a message digest is not known, it can be retrieved
3593 using the following function:
3594
3595 @deftypefun {unsigned int} gcry_md_get_algo_dlen (int @var{algo})
3596
3597 Retrieve the length in bytes of the digest yielded by algorithm
3598 @var{algo}.  This is often used prior to @code{gcry_md_read} to allocate
3599 sufficient memory for the digest.
3600 @end deftypefun
3601
3602
3603 In some situations it might be hard to remember the algorithm used for
3604 the ongoing hashing. The following function might be used to get that
3605 information:
3606
3607 @deftypefun int gcry_md_get_algo (gcry_md_hd_t @var{h})
3608
3609 Retrieve the algorithm used with the handle @var{h}.  Note that this
3610 does not work reliable if more than one algorithm is enabled in @var{h}.
3611 @end deftypefun
3612
3613 The following macro might also be useful:
3614
3615 @deftypefun int gcry_md_is_secure (gcry_md_hd_t @var{h})
3616
3617 This function returns true when the digest object @var{h} is allocated
3618 in "secure memory"; i.e. @var{h} was created with the
3619 @code{GCRY_MD_FLAG_SECURE}.
3620 @end deftypefun
3621
3622 @deftypefun int gcry_md_is_enabled (gcry_md_hd_t @var{h}, int @var{algo})
3623
3624 This function returns true when the algorithm @var{algo} has been
3625 enabled for the digest object @var{h}.
3626 @end deftypefun
3627
3628
3629
3630 Tracking bugs related to hashing is often a cumbersome task which
3631 requires to add a lot of printf statements into the code.
3632 Libgcrypt provides an easy way to avoid this.  The actual data
3633 hashed can be written to files on request.
3634
3635 @deftypefun void gcry_md_debug (gcry_md_hd_t @var{h}, const char *@var{suffix})
3636
3637 Enable debugging for the digest object with handle @var{h}.  This
3638 creates files named @file{dbgmd-<n>.<string>} while doing the
3639 actual hashing.  @var{suffix} is the string part in the filename.  The
3640 number is a counter incremented for each new hashing.  The data in the
3641 file is the raw data as passed to @code{gcry_md_write} or
3642 @code{gcry_md_putc}.  If @code{NULL} is used for @var{suffix}, the
3643 debugging is stopped and the file closed.  This is only rarely required
3644 because @code{gcry_md_close} implicitly stops debugging.
3645 @end deftypefun
3646
3647
3648
3649 @c **********************************************************
3650 @c *******************  MAC Functions  **********************
3651 @c **********************************************************
3652 @node Message Authentication Codes
3653 @chapter Message Authentication Codes
3654
3655 Libgcrypt provides an easy and consistent to use interface for generating
3656 Message Authentication Codes (MAC). MAC generation is buffered and interface
3657 similar to the one used with hash algorithms. The programming model follows
3658 an open/process/close paradigm and is in that similar to other building blocks
3659 provided by Libgcrypt.
3660
3661 @menu
3662 * Available MAC algorithms::   List of MAC algorithms supported by the library.
3663 * Working with MAC algorithms::  List of functions related to MAC algorithms.
3664 @end menu
3665
3666 @node Available MAC algorithms
3667 @section Available MAC algorithms
3668
3669 @c begin table of MAC algorithms
3670 @cindex HMAC-SHA-1
3671 @cindex HMAC-SHA-224, HMAC-SHA-256, HMAC-SHA-384, HMAC-SHA-512
3672 @cindex HMAC-SHA3-224, HMAC-SHA3-256, HMAC-SHA3-384, HMAC-SHA3-512
3673 @cindex HMAC-RIPE-MD-160
3674 @cindex HMAC-MD2, HMAC-MD4, HMAC-MD5
3675 @cindex HMAC-TIGER1
3676 @cindex HMAC-Whirlpool
3677 @cindex HMAC-Stribog-256, HMAC-Stribog-512
3678 @cindex HMAC-GOSTR-3411-94
3679 @table @code
3680 @item GCRY_MAC_NONE
3681 This is not a real algorithm but used by some functions as an error
3682 return value.  This constant is guaranteed to have the value @code{0}.
3683
3684 @item GCRY_MAC_HMAC_SHA256
3685 This is keyed-hash message authentication code (HMAC) message authentication
3686 algorithm based on the SHA-256 hash algorithm.
3687
3688 @item GCRY_MAC_HMAC_SHA224
3689 This is HMAC message authentication algorithm based on the SHA-224 hash
3690 algorithm.
3691
3692 @item GCRY_MAC_HMAC_SHA512
3693 This is HMAC message authentication algorithm based on the SHA-512 hash
3694 algorithm.
3695
3696 @item GCRY_MAC_HMAC_SHA384
3697 This is HMAC message authentication algorithm based on the SHA-384 hash
3698 algorithm.
3699
3700 @item GCRY_MAC_HMAC_SHA3_256
3701 This is HMAC message authentication algorithm based on the SHA3-384 hash
3702 algorithm.
3703
3704 @item GCRY_MAC_HMAC_SHA3_224
3705 This is HMAC message authentication algorithm based on the SHA3-224 hash
3706 algorithm.
3707
3708 @item GCRY_MAC_HMAC_SHA3_512
3709 This is HMAC message authentication algorithm based on the SHA3-512 hash
3710 algorithm.
3711
3712 @item GCRY_MAC_HMAC_SHA3_384
3713 This is HMAC message authentication algorithm based on the SHA3-384 hash
3714 algorithm.
3715
3716 @item GCRY_MAC_HMAC_SHA1
3717 This is HMAC message authentication algorithm based on the SHA-1 hash
3718 algorithm.
3719
3720 @item GCRY_MAC_HMAC_MD5
3721 This is HMAC message authentication algorithm based on the MD5 hash
3722 algorithm.
3723
3724 @item GCRY_MAC_HMAC_MD4
3725 This is HMAC message authentication algorithm based on the MD4 hash
3726 algorithm.
3727
3728 @item GCRY_MAC_HMAC_RMD160
3729 This is HMAC message authentication algorithm based on the RIPE-MD-160 hash
3730 algorithm.
3731
3732 @item GCRY_MAC_HMAC_WHIRLPOOL
3733 This is HMAC message authentication algorithm based on the WHIRLPOOL hash
3734 algorithm.
3735
3736 @item GCRY_MAC_HMAC_GOSTR3411_94
3737 This is HMAC message authentication algorithm based on the GOST R 34.11-94 hash
3738 algorithm.
3739
3740 @item GCRY_MAC_HMAC_STRIBOG256
3741 This is HMAC message authentication algorithm based on the 256-bit hash
3742 algorithm described in GOST R 34.11-2012.
3743
3744 @item GCRY_MAC_HMAC_STRIBOG512
3745 This is HMAC message authentication algorithm based on the 512-bit hash
3746 algorithm described in GOST R 34.11-2012.
3747
3748 @item GCRY_MAC_CMAC_AES
3749 This is CMAC (Cipher-based MAC) message authentication algorithm based on
3750 the AES block cipher algorithm.
3751
3752 @item GCRY_MAC_CMAC_3DES
3753 This is CMAC message authentication algorithm based on the three-key EDE
3754 Triple-DES block cipher algorithm.
3755
3756 @item GCRY_MAC_CMAC_CAMELLIA
3757 This is CMAC message authentication algorithm based on the Camellia block cipher
3758 algorithm.
3759
3760 @item GCRY_MAC_CMAC_CAST5
3761 This is CMAC message authentication algorithm based on the CAST128-5
3762 block cipher algorithm.
3763
3764 @item GCRY_MAC_CMAC_BLOWFISH
3765 This is CMAC message authentication algorithm based on the Blowfish
3766 block cipher algorithm.
3767
3768 @item GCRY_MAC_CMAC_TWOFISH
3769 This is CMAC message authentication algorithm based on the Twofish
3770 block cipher algorithm.
3771
3772 @item GCRY_MAC_CMAC_SERPENT
3773 This is CMAC message authentication algorithm based on the Serpent
3774 block cipher algorithm.
3775
3776 @item GCRY_MAC_CMAC_SEED
3777 This is CMAC message authentication algorithm based on the SEED
3778 block cipher algorithm.
3779
3780 @item GCRY_MAC_CMAC_RFC2268
3781 This is CMAC message authentication algorithm based on the Ron's Cipher 2
3782 block cipher algorithm.
3783
3784 @item GCRY_MAC_CMAC_IDEA
3785 This is CMAC message authentication algorithm based on the IDEA
3786 block cipher algorithm.
3787
3788 @item GCRY_MAC_CMAC_GOST28147
3789 This is CMAC message authentication algorithm based on the GOST 28147-89
3790 block cipher algorithm.
3791
3792 @item GCRY_MAC_GMAC_AES
3793 This is GMAC (GCM mode based MAC) message authentication algorithm based on
3794 the AES block cipher algorithm.
3795
3796 @item GCRY_MAC_GMAC_CAMELLIA
3797 This is GMAC message authentication algorithm based on the Camellia
3798 block cipher algorithm.
3799
3800 @item GCRY_MAC_GMAC_TWOFISH
3801 This is GMAC message authentication algorithm based on the Twofish
3802 block cipher algorithm.
3803
3804 @item GCRY_MAC_GMAC_SERPENT
3805 This is GMAC message authentication algorithm based on the Serpent
3806 block cipher algorithm.
3807
3808 @item GCRY_MAC_GMAC_SEED
3809 This is GMAC message authentication algorithm based on the SEED
3810 block cipher algorithm.
3811
3812 @item GCRY_MAC_POLY1305
3813 This is plain Poly1305 message authentication algorithm, used with
3814 one-time key.
3815
3816 @item GCRY_MAC_POLY1305_AES
3817 This is Poly1305-AES message authentication algorithm, used with
3818 key and one-time nonce.
3819
3820 @item GCRY_MAC_POLY1305_CAMELLIA
3821 This is Poly1305-Camellia message authentication algorithm, used with
3822 key and one-time nonce.
3823
3824 @item GCRY_MAC_POLY1305_TWOFISH
3825 This is Poly1305-Twofish message authentication algorithm, used with
3826 key and one-time nonce.
3827
3828 @item GCRY_MAC_POLY1305_SERPENT
3829 This is Poly1305-Serpent message authentication algorithm, used with
3830 key and one-time nonce.
3831
3832 @item GCRY_MAC_POLY1305_SEED
3833 This is Poly1305-SEED message authentication algorithm, used with
3834 key and one-time nonce.
3835
3836 @end table
3837 @c end table of MAC algorithms
3838
3839 @node Working with MAC algorithms
3840 @section Working with MAC algorithms
3841
3842 To use most of these function it is necessary to create a context;
3843 this is done using:
3844
3845 @deftypefun gcry_error_t gcry_mac_open (gcry_mac_hd_t *@var{hd}, int @var{algo}, unsigned int @var{flags}, gcry_ctx_t @var{ctx})
3846
3847 Create a MAC object for algorithm @var{algo}. @var{flags} may be given as an
3848 bitwise OR of constants described below. @var{hd} is guaranteed to either
3849 receive a valid handle or NULL. @var{ctx} is context object to associate MAC
3850 object with. @var{ctx} maybe set to NULL.
3851
3852 For a list of supported algorithms, see @ref{Available MAC algorithms}.
3853
3854 The flags allowed for @var{mode} are:
3855
3856 @c begin table of MAC flags
3857 @table @code
3858 @item GCRY_MAC_FLAG_SECURE
3859 Allocate all buffers and the resulting MAC in "secure memory".  Use this if the
3860 MAC data is highly confidential.
3861
3862 @end table
3863 @c begin table of MAC flags
3864
3865 @end deftypefun
3866 @c end function gcry_mac_open
3867
3868
3869 In order to use a handle for performing MAC algorithm operations, a
3870 `key' has to be set first:
3871
3872 @deftypefun gcry_error_t gcry_mac_setkey (gcry_mac_hd_t @var{h}, const void *@var{key}, size_t @var{keylen})
3873
3874 Set the MAC key to the value of @var{key} of length @var{keylen} bytes. With
3875 HMAC algorithms, there is no restriction on the length of the key. With CMAC
3876 algorithms, the length of the key is restricted to those supported by the
3877 underlying block cipher.
3878 @end deftypefun
3879
3880
3881 GMAC algorithms and Poly1305-with-cipher algorithms need initialization vector to be set,
3882 which can be performed with function:
3883
3884 @deftypefun gcry_error_t gcry_mac_setiv (gcry_mac_hd_t @var{h}, const void *@var{iv}, size_t @var{ivlen})
3885
3886 Set the IV to the value of @var{iv} of length @var{ivlen} bytes.
3887 @end deftypefun
3888
3889
3890 After you are done with the MAC calculation, you should release the resources
3891 by using:
3892
3893 @deftypefun void gcry_mac_close (gcry_mac_hd_t @var{h})
3894
3895 Release all resources of MAC context @var{h}.  @var{h} should not be
3896 used after a call to this function.  A @code{NULL} passed as @var{h} is
3897 ignored.  The function also clears all sensitive information associated
3898 with this handle.
3899 @end deftypefun
3900
3901
3902 Often you have to do several MAC operations using the same algorithm.
3903 To avoid the overhead of creating and releasing context, a reset function
3904 is provided:
3905
3906 @deftypefun gcry_error_t gcry_mac_reset (gcry_mac_hd_t @var{h})
3907
3908 Reset the current context to its initial state. This is effectively identical
3909 to a close followed by an open and setting same key.
3910
3911 Note that gcry_mac_reset is implemented as a macro.
3912 @end deftypefun
3913
3914
3915 Now that we have prepared everything to calculate MAC, it is time to
3916 see how it is actually done.
3917
3918 @deftypefun gcry_error_t gcry_mac_write (gcry_mac_hd_t @var{h}, const void *@var{buffer}, size_t @var{length})
3919
3920 Pass @var{length} bytes of the data in @var{buffer} to the MAC object
3921 with handle @var{h} to update the MAC values.  If this function is
3922 used after the context has been finalized, it will keep on pushing the
3923 data through the algorithm specific transform function and thereby
3924 change the context; however the results are not meaningful and this
3925 feature is only available to mitigate timing attacks.
3926 @end deftypefun
3927
3928 The way to read out the calculated MAC is by using the function:
3929
3930 @deftypefun gcry_error_t gcry_mac_read (gcry_mac_hd_t @var{h}, void *@var{buffer}, size_t *@var{length})
3931
3932 @code{gcry_mac_read} returns the MAC after finalizing the calculation.
3933 Function copies the resulting MAC value to @var{buffer} of the length
3934 @var{length}. If @var{length} is larger than length of resulting MAC value,
3935 then length of MAC is returned through @var{length}.
3936 @end deftypefun
3937
3938 To compare existing MAC value with recalculated MAC, one is to use the function:
3939
3940 @deftypefun gcry_error_t gcry_mac_verify (gcry_mac_hd_t @var{h}, void *@var{buffer}, size_t @var{length})
3941
3942 @code{gcry_mac_verify} finalizes MAC calculation and compares result with
3943 @var{length} bytes of data in @var{buffer}. Error code @code{GPG_ERR_CHECKSUM}
3944 is returned if the MAC value in the buffer @var{buffer} does not match
3945 the MAC calculated in object @var{h}.
3946 @end deftypefun
3947
3948
3949 In some situations it might be hard to remember the algorithm used for
3950 the MAC calculation. The following function might be used to get that
3951 information:
3952
3953 @deftypefun {int} gcry_mac_get_algo (gcry_mac_hd_t @var{h})
3954
3955 Retrieve the algorithm used with the handle @var{h}.
3956 @end deftypefun
3957
3958
3959 @c ***********************************
3960 @c ***** MAC info functions **********
3961 @c ***********************************
3962
3963 MAC algorithms are identified by internal algorithm numbers (see
3964 @code{gcry_mac_open} for a list).  However, in most applications they are
3965 used by names, so two functions are available to map between string
3966 representations and MAC algorithm identifiers.
3967
3968 @deftypefun {const char *} gcry_mac_algo_name (int @var{algo})
3969
3970 Map the MAC algorithm id @var{algo} to a string representation of the
3971 algorithm name.  For unknown algorithms this function returns the
3972 string @code{"?"}.  This function should not be used to test for the
3973 availability of an algorithm.
3974 @end deftypefun
3975
3976 @deftypefun int gcry_mac_map_name (const char *@var{name})
3977
3978 Map the algorithm with @var{name} to a MAC algorithm identifier.
3979 Returns 0 if the algorithm name is not known. This function should not
3980 be used to test for the availability of an algorithm.
3981 @end deftypefun
3982
3983
3984 To test whether an algorithm is actually available for use, the
3985 following macro should be used:
3986
3987 @deftypefun gcry_error_t gcry_mac_test_algo (int @var{algo})
3988
3989 The macro returns 0 if the MAC algorithm @var{algo} is available for use.
3990 @end deftypefun
3991
3992
3993 If the length of a message digest is not known, it can be retrieved
3994 using the following function:
3995
3996 @deftypefun {unsigned int} gcry_mac_get_algo_maclen (int @var{algo})
3997
3998 Retrieve the length in bytes of the MAC yielded by algorithm @var{algo}.
3999 This is often used prior to @code{gcry_mac_read} to allocate sufficient memory
4000 for the MAC value. On error @code{0} is returned.
4001 @end deftypefun
4002
4003
4004 @deftypefun {unsigned int} gcry_mac_get_algo_keylen (@var{algo})
4005
4006 This function returns length of the key for MAC algorithm @var{algo}.  If
4007 the algorithm supports multiple key lengths, the default supported key
4008 length is returned.  On error @code{0} is returned.  The key length is
4009 returned as number of octets.
4010 @end deftypefun
4011
4012
4013
4014 @c *******************************************************
4015 @c *******************  KDF  *****************************
4016 @c *******************************************************
4017 @node Key Derivation
4018 @chapter Key Derivation
4019
4020 @acronym{Libgcypt} provides a general purpose function to derive keys
4021 from strings.
4022
4023 @deftypefun gpg_error_t gcry_kdf_derive ( @
4024             @w{const void *@var{passphrase}}, @w{size_t @var{passphraselen}}, @
4025             @w{int @var{algo}}, @w{int @var{subalgo}}, @
4026             @w{const void *@var{salt}}, @w{size_t @var{saltlen}}, @
4027             @w{unsigned long @var{iterations}}, @
4028             @w{size_t @var{keysize}}, @w{void *@var{keybuffer}} )
4029
4030
4031 Derive a key from a passphrase.  @var{keysize} gives the requested
4032 size of the keys in octets.  @var{keybuffer} is a caller provided
4033 buffer filled on success with the derived key.  The input passphrase
4034 is taken from @var{passphrase} which is an arbitrary memory buffer of
4035 @var{passphraselen} octets.  @var{algo} specifies the KDF algorithm to
4036 use; see below.  @var{subalgo} specifies an algorithm used internally
4037 by the KDF algorithms; this is usually a hash algorithm but certain
4038 KDF algorithms may use it differently.  @var{salt} is a salt of length
4039 @var{saltlen} octets, as needed by most KDF algorithms.
4040 @var{iterations} is a positive integer parameter to most KDFs.
4041
4042 @noindent
4043 On success 0 is returned; on failure an error code.
4044
4045 @noindent
4046 Currently supported KDFs (parameter @var{algo}):
4047
4048 @table @code
4049 @item GCRY_KDF_SIMPLE_S2K
4050 The OpenPGP simple S2K algorithm (cf. RFC4880).  Its use is strongly
4051 deprecated.  @var{salt} and @var{iterations} are not needed and may be
4052 passed as @code{NULL}/@code{0}.
4053
4054 @item GCRY_KDF_SALTED_S2K
4055 The OpenPGP salted S2K algorithm (cf. RFC4880).  Usually not used.
4056 @var{iterations} is not needed and may be passed as @code{0}.  @var{saltlen}
4057 must be given as 8.
4058
4059 @item GCRY_KDF_ITERSALTED_S2K
4060 The OpenPGP iterated+salted S2K algorithm (cf. RFC4880).  This is the
4061 default for most OpenPGP applications.  @var{saltlen} must be given as
4062 8.  Note that OpenPGP defines a special encoding of the
4063 @var{iterations}; however this function takes the plain decoded
4064 iteration count.
4065
4066 @item GCRY_KDF_PBKDF2
4067 The PKCS#5 Passphrase Based Key Derivation Function number 2.
4068
4069 @item GCRY_KDF_SCRYPT
4070 The SCRYPT Key Derivation Function.  The subalgorithm is used to specify
4071 the CPU/memory cost parameter N, and the number of iterations
4072 is used for the parallelization parameter p.  The block size is fixed
4073 at 8 in the current implementation.
4074
4075 @end table
4076 @end deftypefun
4077
4078
4079 @c **********************************************************
4080 @c *******************  Random  *****************************
4081 @c **********************************************************
4082 @node Random Numbers
4083 @chapter Random Numbers
4084
4085 @menu
4086 * Quality of random numbers::   Libgcrypt uses different quality levels.
4087 * Retrieving random numbers::   How to retrieve random numbers.
4088 @end menu
4089
4090 @node Quality of random numbers
4091 @section Quality of random numbers
4092
4093 @acronym{Libgcypt} offers random numbers of different quality levels:
4094
4095 @deftp {Data type} gcry_random_level_t
4096 The constants for the random quality levels are of this enum type.
4097 @end deftp
4098
4099 @table @code
4100 @item GCRY_WEAK_RANDOM
4101 For all functions, except for @code{gcry_mpi_randomize}, this level maps
4102 to GCRY_STRONG_RANDOM.  If you do not want this, consider using
4103 @code{gcry_create_nonce}.
4104 @item GCRY_STRONG_RANDOM
4105 Use this level for session keys and similar purposes.
4106 @item GCRY_VERY_STRONG_RANDOM
4107 Use this level for long term key material.
4108 @end table
4109
4110 @node Retrieving random numbers
4111 @section Retrieving random numbers
4112
4113 @deftypefun void gcry_randomize (unsigned char *@var{buffer}, size_t @var{length}, enum gcry_random_level @var{level})
4114
4115 Fill @var{buffer} with @var{length} random bytes using a random quality
4116 as defined by @var{level}.
4117 @end deftypefun
4118
4119 @deftypefun {void *} gcry_random_bytes (size_t @var{nbytes}, enum gcry_random_level @var{level})
4120
4121 Convenience function to allocate a memory block consisting of
4122 @var{nbytes} fresh random bytes using a random quality as defined by
4123 @var{level}.
4124 @end deftypefun
4125
4126 @deftypefun {void *} gcry_random_bytes_secure (size_t @var{nbytes}, enum gcry_random_level @var{level})
4127
4128 Convenience function to allocate a memory block consisting of
4129 @var{nbytes} fresh random bytes using a random quality as defined by
4130 @var{level}.  This function differs from @code{gcry_random_bytes} in
4131 that the returned buffer is allocated in a ``secure'' area of the
4132 memory.
4133 @end deftypefun
4134
4135 @deftypefun void gcry_create_nonce (unsigned char *@var{buffer}, size_t @var{length})
4136
4137 Fill @var{buffer} with @var{length} unpredictable bytes.  This is
4138 commonly called a nonce and may also be used for initialization
4139 vectors and padding.  This is an extra function nearly independent of
4140 the other random function for 3 reasons: It better protects the
4141 regular random generator's internal state, provides better performance
4142 and does not drain the precious entropy pool.
4143
4144 @end deftypefun
4145
4146
4147
4148 @c **********************************************************
4149 @c *******************  S-Expressions ***********************
4150 @c **********************************************************
4151 @node S-expressions
4152 @chapter S-expressions
4153
4154 S-expressions are used by the public key functions to pass complex data
4155 structures around.  These LISP like objects are used by some
4156 cryptographic protocols (cf. RFC-2692) and Libgcrypt provides functions
4157 to parse and construct them.  For detailed information, see
4158 @cite{Ron Rivest, code and description of S-expressions,
4159 @uref{http://theory.lcs.mit.edu/~rivest/sexp.html}}.
4160
4161 @menu
4162 * Data types for S-expressions::  Data types related with S-expressions.
4163 * Working with S-expressions::  How to work with S-expressions.
4164 @end menu
4165
4166 @node Data types for S-expressions
4167 @section Data types for S-expressions
4168
4169 @deftp {Data type} gcry_sexp_t
4170 The @code{gcry_sexp_t} type describes an object with the Libgcrypt internal
4171 representation of an S-expression.
4172 @end deftp
4173
4174 @node Working with S-expressions
4175 @section Working with S-expressions
4176
4177 @noindent
4178 There are several functions to create an Libgcrypt S-expression object
4179 from its external representation or from a string template.  There is
4180 also a function to convert the internal representation back into one of
4181 the external formats:
4182
4183
4184 @deftypefun gcry_error_t gcry_sexp_new (@w{gcry_sexp_t *@var{r_sexp}}, @w{const void *@var{buffer}}, @w{size_t @var{length}}, @w{int @var{autodetect}})
4185
4186 This is the generic function to create an new S-expression object from
4187 its external representation in @var{buffer} of @var{length} bytes.  On
4188 success the result is stored at the address given by @var{r_sexp}.
4189 With @var{autodetect} set to 0, the data in @var{buffer} is expected to
4190 be in canonized format, with @var{autodetect} set to 1 the parses any of
4191 the defined external formats.  If @var{buffer} does not hold a valid
4192 S-expression an error code is returned and @var{r_sexp} set to
4193 @code{NULL}.
4194 Note that the caller is responsible for releasing the newly allocated
4195 S-expression using @code{gcry_sexp_release}.
4196 @end deftypefun
4197
4198 @deftypefun gcry_error_t gcry_sexp_create (@w{gcry_sexp_t *@var{r_sexp}}, @w{void *@var{buffer}}, @w{size_t @var{length}}, @w{int @var{autodetect}}, @w{void (*@var{freefnc})(void*)})
4199
4200 This function is identical to @code{gcry_sexp_new} but has an extra
4201 argument @var{freefnc}, which, when not set to @code{NULL}, is expected
4202 to be a function to release the @var{buffer}; most likely the standard
4203 @code{free} function is used for this argument.  This has the effect of
4204 transferring the ownership of @var{buffer} to the created object in
4205 @var{r_sexp}.  The advantage of using this function is that Libgcrypt
4206 might decide to directly use the provided buffer and thus avoid extra
4207 copying.
4208 @end deftypefun
4209
4210 @deftypefun gcry_error_t gcry_sexp_sscan (@w{gcry_sexp_t *@var{r_sexp}}, @w{size_t *@var{erroff}}, @w{const char *@var{buffer}}, @w{size_t @var{length}})
4211
4212 This is another variant of the above functions.  It behaves nearly
4213 identical but provides an @var{erroff} argument which will receive the
4214 offset into the buffer where the parsing stopped on error.
4215 @end deftypefun
4216
4217 @deftypefun gcry_error_t gcry_sexp_build (@w{gcry_sexp_t *@var{r_sexp}}, @w{size_t *@var{erroff}}, @w{const char *@var{format}, ...})
4218
4219 This function creates an internal S-expression from the string template
4220 @var{format} and stores it at the address of @var{r_sexp}. If there is a
4221 parsing error, the function returns an appropriate error code and stores
4222 the offset into @var{format} where the parsing stopped in @var{erroff}.
4223 The function supports a couple of printf-like formatting characters and
4224 expects arguments for some of these escape sequences right after
4225 @var{format}.  The following format characters are defined:
4226
4227 @table @samp
4228 @item %m
4229 The next argument is expected to be of type @code{gcry_mpi_t} and a copy of
4230 its value is inserted into the resulting S-expression.  The MPI is
4231 stored as a signed integer.
4232 @item %M
4233 The next argument is expected to be of type @code{gcry_mpi_t} and a copy of
4234 its value is inserted into the resulting S-expression.  The MPI is
4235 stored as an unsigned integer.
4236 @item %s
4237 The next argument is expected to be of type @code{char *} and that
4238 string is inserted into the resulting S-expression.
4239 @item %d
4240 The next argument is expected to be of type @code{int} and its value is
4241 inserted into the resulting S-expression.
4242 @item %u
4243 The next argument is expected to be of type @code{unsigned int} and
4244 its value is inserted into the resulting S-expression.
4245 @item %b
4246 The next argument is expected to be of type @code{int} directly
4247 followed by an argument of type @code{char *}.  This represents a
4248 buffer of given length to be inserted into the resulting S-expression.
4249 @item %S
4250 The next argument is expected to be of type @code{gcry_sexp_t} and a
4251 copy of that S-expression is embedded in the resulting S-expression.
4252 The argument needs to be a regular S-expression, starting with a
4253 parenthesis.
4254
4255 @end table
4256
4257 @noindent
4258 No other format characters are defined and would return an error.  Note
4259 that the format character @samp{%%} does not exists, because a percent
4260 sign is not a valid character in an S-expression.
4261 @end deftypefun
4262
4263 @deftypefun void gcry_sexp_release (@w{gcry_sexp_t @var{sexp}})
4264
4265 Release the S-expression object @var{sexp}.  If the S-expression is
4266 stored in secure memory it explicitly zeroises that memory; note that
4267 this is done in addition to the zeroisation always done when freeing
4268 secure memory.
4269 @end deftypefun
4270
4271
4272 @noindent
4273 The next 2 functions are used to convert the internal representation
4274 back into a regular external S-expression format and to show the
4275 structure for debugging.
4276
4277 @deftypefun size_t gcry_sexp_sprint (@w{gcry_sexp_t @var{sexp}}, @w{int @var{mode}}, @w{char *@var{buffer}}, @w{size_t @var{maxlength}})
4278
4279 Copies the S-expression object @var{sexp} into @var{buffer} using the
4280 format specified in @var{mode}.  @var{maxlength} must be set to the
4281 allocated length of @var{buffer}.  The function returns the actual
4282 length of valid bytes put into @var{buffer} or 0 if the provided buffer
4283 is too short.  Passing @code{NULL} for @var{buffer} returns the required
4284 length for @var{buffer}.  For convenience reasons an extra byte with
4285 value 0 is appended to the buffer.
4286
4287 @noindent
4288 The following formats are supported:
4289
4290 @table @code
4291 @item GCRYSEXP_FMT_DEFAULT
4292 Returns a convenient external S-expression representation.
4293
4294 @item GCRYSEXP_FMT_CANON
4295 Return the S-expression in canonical format.
4296
4297 @item GCRYSEXP_FMT_BASE64
4298 Not currently supported.
4299
4300 @item GCRYSEXP_FMT_ADVANCED
4301 Returns the S-expression in advanced format.
4302 @end table
4303 @end deftypefun
4304
4305 @deftypefun void gcry_sexp_dump (@w{gcry_sexp_t @var{sexp}})
4306
4307 Dumps @var{sexp} in a format suitable for debugging to Libgcrypt's
4308 logging stream.
4309 @end deftypefun
4310
4311 @noindent
4312 Often canonical encoding is used in the external representation.  The
4313 following function can be used to check for valid encoding and to learn
4314 the length of the S-expression.
4315
4316 @deftypefun size_t gcry_sexp_canon_len (@w{const unsigned char *@var{buffer}}, @w{size_t @var{length}}, @w{size_t *@var{erroff}}, @w{int *@var{errcode}})
4317
4318 Scan the canonical encoded @var{buffer} with implicit length values and
4319 return the actual length this S-expression uses.  For a valid S-expression
4320 it should never return 0.  If @var{length} is not 0, the maximum
4321 length to scan is given; this can be used for syntax checks of
4322 data passed from outside.  @var{errcode} and @var{erroff} may both be
4323 passed as @code{NULL}.
4324
4325 @end deftypefun
4326
4327
4328 @noindent
4329 There are functions to parse S-expressions and retrieve elements:
4330
4331 @deftypefun gcry_sexp_t gcry_sexp_find_token (@w{const gcry_sexp_t @var{list}}, @w{const char *@var{token}}, @w{size_t @var{toklen}})
4332
4333 Scan the S-expression for a sublist with a type (the car of the list)
4334 matching the string @var{token}.  If @var{toklen} is not 0, the token is
4335 assumed to be raw memory of this length.  The function returns a newly
4336 allocated S-expression consisting of the found sublist or @code{NULL}
4337 when not found.
4338 @end deftypefun
4339
4340
4341 @deftypefun int gcry_sexp_length (@w{const gcry_sexp_t @var{list}})
4342
4343 Return the length of the @var{list}.  For a valid S-expression this
4344 should be at least 1.
4345 @end deftypefun
4346
4347
4348 @deftypefun gcry_sexp_t gcry_sexp_nth (@w{const gcry_sexp_t @var{list}}, @w{int @var{number}})
4349
4350 Create and return a new S-expression from the element with index @var{number} in
4351 @var{list}.  Note that the first element has the index 0.  If there is
4352 no such element, @code{NULL} is returned.
4353 @end deftypefun
4354
4355 @deftypefun gcry_sexp_t gcry_sexp_car (@w{const gcry_sexp_t @var{list}})
4356
4357 Create and return a new S-expression from the first element in
4358 @var{list}; this is called the "type" and should always exist per
4359 S-expression specification and in general be a string.  @code{NULL} is
4360 returned in case of a problem.
4361 @end deftypefun
4362
4363 @deftypefun gcry_sexp_t gcry_sexp_cdr (@w{const gcry_sexp_t @var{list}})
4364
4365 Create and return a new list form all elements except for the first one.
4366 Note that this function may return an invalid S-expression because it