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