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