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