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