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