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