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