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