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