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