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