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