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