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