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