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