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