Flag the _ac_ functions as deprecated.
[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 definitions 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 @item GCRYCTL_DISABLE_HWF; Arguments: const char *name
818
819 Libgcrypt detects certain features of the CPU at startup time.  For
820 performace tests it is sometimes required not to use such a feature.
821 This option may be used to disabale a certain feature; i.e. Libgcrypt
822 behaves as if this feature has not been detected.  Note that the
823 detection code might be run if the feature has been disabled.  This
824 command must be used at initialization time; i.e. before calling
825 @code{gcry_check_version}.
826
827 @end table
828
829 @end deftypefun
830
831 @node Modules
832 @section Modules
833
834 Libgcrypt supports the use of `extension modules', which
835 implement algorithms in addition to those already built into the library
836 directly.
837
838 @deftp {Data type} gcry_module_t
839 This data type represents a `module'.
840 @end deftp
841
842 Functions registering modules provided by the user take a `module
843 specification structure' as input and return a value of
844 @code{gcry_module_t} and an ID that is unique in the modules'
845 category.  This ID can be used to reference the newly registered
846 module.  After registering a module successfully, the new functionality
847 should be able to be used through the normal functions provided by
848 Libgcrypt until it is unregistered again.
849
850 @c **********************************************************
851 @c *******************  Errors  ****************************
852 @c **********************************************************
853 @node Error Handling
854 @section Error Handling
855
856 Many functions in Libgcrypt can return an error if they
857 fail.  For this reason, the application should always catch the error
858 condition and take appropriate measures, for example by releasing the
859 resources and passing the error up to the caller, or by displaying a
860 descriptive message to the user and cancelling the operation.
861
862 Some error values do not indicate a system error or an error in the
863 operation, but the result of an operation that failed properly.  For
864 example, if you try to decrypt a tempered message, the decryption will
865 fail.  Another error value actually means that the end of a data
866 buffer or list has been reached.  The following descriptions explain
867 for many error codes what they mean usually.  Some error values have
868 specific meanings if returned by a certain functions.  Such cases are
869 described in the documentation of those functions.
870
871 Libgcrypt uses the @code{libgpg-error} library.  This allows to share
872 the error codes with other components of the GnuPG system, and to pass
873 error values transparently from the crypto engine, or some helper
874 application of the crypto engine, to the user.  This way no
875 information is lost.  As a consequence, Libgcrypt does not use its own
876 identifiers for error codes, but uses those provided by
877 @code{libgpg-error}.  They usually start with @code{GPG_ERR_}.
878
879 However, Libgcrypt does provide aliases for the functions
880 defined in libgpg-error, which might be preferred for name space
881 consistency.
882
883
884 Most functions in Libgcrypt return an error code in the case
885 of failure.  For this reason, the application should always catch the
886 error condition and take appropriate measures, for example by
887 releasing the resources and passing the error up to the caller, or by
888 displaying a descriptive message to the user and canceling the
889 operation.
890
891 Some error values do not indicate a system error or an error in the
892 operation, but the result of an operation that failed properly.
893
894 GnuPG components, including Libgcrypt, use an extra library named
895 libgpg-error to provide a common error handling scheme.  For more
896 information on libgpg-error, see the according manual.
897
898 @menu
899 * Error Values::                The error value and what it means.
900 * Error Sources::               A list of important error sources.
901 * Error Codes::                 A list of important error codes.
902 * Error Strings::               How to get a descriptive string from a value.
903 @end menu
904
905
906 @node Error Values
907 @subsection Error Values
908 @cindex error values
909 @cindex error codes
910 @cindex error sources
911
912 @deftp {Data type} {gcry_err_code_t}
913 The @code{gcry_err_code_t} type is an alias for the
914 @code{libgpg-error} type @code{gpg_err_code_t}.  The error code
915 indicates the type of an error, or the reason why an operation failed.
916
917 A list of important error codes can be found in the next section.
918 @end deftp
919
920 @deftp {Data type} {gcry_err_source_t}
921 The @code{gcry_err_source_t} type is an alias for the
922 @code{libgpg-error} type @code{gpg_err_source_t}.  The error source
923 has not a precisely defined meaning.  Sometimes it is the place where
924 the error happened, sometimes it is the place where an error was
925 encoded into an error value.  Usually the error source will give an
926 indication to where to look for the problem.  This is not always true,
927 but it is attempted to achieve this goal.
928
929 A list of important error sources can be found in the next section.
930 @end deftp
931
932 @deftp {Data type} {gcry_error_t}
933 The @code{gcry_error_t} type is an alias for the @code{libgpg-error}
934 type @code{gpg_error_t}.  An error value like this has always two
935 components, an error code and an error source.  Both together form the
936 error value.
937
938 Thus, the error value can not be directly compared against an error
939 code, but the accessor functions described below must be used.
940 However, it is guaranteed that only 0 is used to indicate success
941 (@code{GPG_ERR_NO_ERROR}), and that in this case all other parts of
942 the error value are set to 0, too.
943
944 Note that in Libgcrypt, the error source is used purely for
945 diagnostic purposes.  Only the error code should be checked to test
946 for a certain outcome of a function.  The manual only documents the
947 error code part of an error value.  The error source is left
948 unspecified and might be anything.
949 @end deftp
950
951 @deftypefun {gcry_err_code_t} gcry_err_code (@w{gcry_error_t @var{err}})
952 The static inline function @code{gcry_err_code} returns the
953 @code{gcry_err_code_t} component of the error value @var{err}.  This
954 function must be used to extract the error code from an error value in
955 order to compare it with the @code{GPG_ERR_*} error code macros.
956 @end deftypefun
957
958 @deftypefun {gcry_err_source_t} gcry_err_source (@w{gcry_error_t @var{err}})
959 The static inline function @code{gcry_err_source} returns the
960 @code{gcry_err_source_t} component of the error value @var{err}.  This
961 function must be used to extract the error source from an error value in
962 order to compare it with the @code{GPG_ERR_SOURCE_*} error source macros.
963 @end deftypefun
964
965 @deftypefun {gcry_error_t} gcry_err_make (@w{gcry_err_source_t @var{source}}, @w{gcry_err_code_t @var{code}})
966 The static inline function @code{gcry_err_make} returns the error
967 value consisting of the error source @var{source} and the error code
968 @var{code}.
969
970 This function can be used in callback functions to construct an error
971 value to return it to the library.
972 @end deftypefun
973
974 @deftypefun {gcry_error_t} gcry_error (@w{gcry_err_code_t @var{code}})
975 The static inline function @code{gcry_error} returns the error value
976 consisting of the default error source and the error code @var{code}.
977
978 For @acronym{GCRY} applications, the default error source is
979 @code{GPG_ERR_SOURCE_USER_1}.  You can define
980 @code{GCRY_ERR_SOURCE_DEFAULT} before including @file{gcrypt.h} to
981 change this default.
982
983 This function can be used in callback functions to construct an error
984 value to return it to the library.
985 @end deftypefun
986
987 The @code{libgpg-error} library provides error codes for all system
988 error numbers it knows about.  If @var{err} is an unknown error
989 number, the error code @code{GPG_ERR_UNKNOWN_ERRNO} is used.  The
990 following functions can be used to construct error values from system
991 errno numbers.
992
993 @deftypefun {gcry_error_t} gcry_err_make_from_errno (@w{gcry_err_source_t @var{source}}, @w{int @var{err}})
994 The function @code{gcry_err_make_from_errno} is like
995 @code{gcry_err_make}, but it takes a system error like @code{errno}
996 instead of a @code{gcry_err_code_t} error code.
997 @end deftypefun
998
999 @deftypefun {gcry_error_t} gcry_error_from_errno (@w{int @var{err}})
1000 The function @code{gcry_error_from_errno} is like @code{gcry_error},
1001 but it takes a system error like @code{errno} instead of a
1002 @code{gcry_err_code_t} error code.
1003 @end deftypefun
1004
1005 Sometimes you might want to map system error numbers to error codes
1006 directly, or map an error code representing a system error back to the
1007 system error number.  The following functions can be used to do that.
1008
1009 @deftypefun {gcry_err_code_t} gcry_err_code_from_errno (@w{int @var{err}})
1010 The function @code{gcry_err_code_from_errno} returns the error code
1011 for the system error @var{err}.  If @var{err} is not a known system
1012 error, the function returns @code{GPG_ERR_UNKNOWN_ERRNO}.
1013 @end deftypefun
1014
1015 @deftypefun {int} gcry_err_code_to_errno (@w{gcry_err_code_t @var{err}})
1016 The function @code{gcry_err_code_to_errno} returns the system error
1017 for the error code @var{err}.  If @var{err} is not an error code
1018 representing a system error, or if this system error is not defined on
1019 this system, the function returns @code{0}.
1020 @end deftypefun
1021
1022
1023 @node Error Sources
1024 @subsection Error Sources
1025 @cindex error codes, list of
1026
1027 The library @code{libgpg-error} defines an error source for every
1028 component of the GnuPG system.  The error source part of an error
1029 value is not well defined.  As such it is mainly useful to improve the
1030 diagnostic error message for the user.
1031
1032 If the error code part of an error value is @code{0}, the whole error
1033 value will be @code{0}.  In this case the error source part is of
1034 course @code{GPG_ERR_SOURCE_UNKNOWN}.
1035
1036 The list of error sources that might occur in applications using
1037 @acronym{Libgcrypt} is:
1038
1039 @table @code
1040 @item GPG_ERR_SOURCE_UNKNOWN
1041 The error source is not known.  The value of this error source is
1042 @code{0}.
1043
1044 @item GPG_ERR_SOURCE_GPGME
1045 The error source is @acronym{GPGME} itself.
1046
1047 @item GPG_ERR_SOURCE_GPG
1048 The error source is GnuPG, which is the crypto engine used for the
1049 OpenPGP protocol.
1050
1051 @item GPG_ERR_SOURCE_GPGSM
1052 The error source is GPGSM, which is the crypto engine used for the
1053 OpenPGP protocol.
1054
1055 @item GPG_ERR_SOURCE_GCRYPT
1056 The error source is @code{libgcrypt}, which is used by crypto engines
1057 to perform cryptographic operations.
1058
1059 @item GPG_ERR_SOURCE_GPGAGENT
1060 The error source is @command{gpg-agent}, which is used by crypto
1061 engines to perform operations with the secret key.
1062
1063 @item GPG_ERR_SOURCE_PINENTRY
1064 The error source is @command{pinentry}, which is used by
1065 @command{gpg-agent} to query the passphrase to unlock a secret key.
1066
1067 @item GPG_ERR_SOURCE_SCD
1068 The error source is the SmartCard Daemon, which is used by
1069 @command{gpg-agent} to delegate operations with the secret key to a
1070 SmartCard.
1071
1072 @item GPG_ERR_SOURCE_KEYBOX
1073 The error source is @code{libkbx}, a library used by the crypto
1074 engines to manage local keyrings.
1075
1076 @item GPG_ERR_SOURCE_USER_1
1077 @item GPG_ERR_SOURCE_USER_2
1078 @item GPG_ERR_SOURCE_USER_3
1079 @item GPG_ERR_SOURCE_USER_4
1080 These error sources are not used by any GnuPG component and can be
1081 used by other software.  For example, applications using
1082 Libgcrypt can use them to mark error values coming from callback
1083 handlers.  Thus @code{GPG_ERR_SOURCE_USER_1} is the default for errors
1084 created with @code{gcry_error} and @code{gcry_error_from_errno},
1085 unless you define @code{GCRY_ERR_SOURCE_DEFAULT} before including
1086 @file{gcrypt.h}.
1087 @end table
1088
1089
1090 @node Error Codes
1091 @subsection Error Codes
1092 @cindex error codes, list of
1093
1094 The library @code{libgpg-error} defines many error values.  The
1095 following list includes the most important error codes.
1096
1097 @table @code
1098 @item GPG_ERR_EOF
1099 This value indicates the end of a list, buffer or file.
1100
1101 @item GPG_ERR_NO_ERROR
1102 This value indicates success.  The value of this error code is
1103 @code{0}.  Also, it is guaranteed that an error value made from the
1104 error code @code{0} will be @code{0} itself (as a whole).  This means
1105 that the error source information is lost for this error code,
1106 however, as this error code indicates that no error occurred, this is
1107 generally not a problem.
1108
1109 @item GPG_ERR_GENERAL
1110 This value means that something went wrong, but either there is not
1111 enough information about the problem to return a more useful error
1112 value, or there is no separate error value for this type of problem.
1113
1114 @item GPG_ERR_ENOMEM
1115 This value means that an out-of-memory condition occurred.
1116
1117 @item GPG_ERR_E...
1118 System errors are mapped to GPG_ERR_EFOO where FOO is the symbol for
1119 the system error.
1120
1121 @item GPG_ERR_INV_VALUE
1122 This value means that some user provided data was out of range.
1123
1124 @item GPG_ERR_UNUSABLE_PUBKEY
1125 This value means that some recipients for a message were invalid.
1126
1127 @item GPG_ERR_UNUSABLE_SECKEY
1128 This value means that some signers were invalid.
1129
1130 @item GPG_ERR_NO_DATA
1131 This value means that data was expected where no data was found.
1132
1133 @item GPG_ERR_CONFLICT
1134 This value means that a conflict of some sort occurred.
1135
1136 @item GPG_ERR_NOT_IMPLEMENTED
1137 This value indicates that the specific function (or operation) is not
1138 implemented.  This error should never happen.  It can only occur if
1139 you use certain values or configuration options which do not work,
1140 but for which we think that they should work at some later time.
1141
1142 @item GPG_ERR_DECRYPT_FAILED
1143 This value indicates that a decryption operation was unsuccessful.
1144
1145 @item GPG_ERR_WRONG_KEY_USAGE
1146 This value indicates that a key is not used appropriately.
1147
1148 @item GPG_ERR_NO_SECKEY
1149 This value indicates that no secret key for the user ID is available.
1150
1151 @item GPG_ERR_UNSUPPORTED_ALGORITHM
1152 This value means a verification failed because the cryptographic
1153 algorithm is not supported by the crypto backend.
1154
1155 @item GPG_ERR_BAD_SIGNATURE
1156 This value means a verification failed because the signature is bad.
1157
1158 @item GPG_ERR_NO_PUBKEY
1159 This value means a verification failed because the public key is not
1160 available.
1161
1162 @item GPG_ERR_NOT_OPERATIONAL
1163 This value means that the library is not yet in state which allows to
1164 use this function.  This error code is in particular returned if
1165 Libgcrypt is operated in FIPS mode and the internal state of the
1166 library does not yet or not anymore allow the use of a service.
1167
1168 This error code is only available with newer libgpg-error versions, thus
1169 you might see ``invalid error code'' when passing this to
1170 @code{gpg_strerror}.  The numeric value of this error code is 176.
1171
1172 @item GPG_ERR_USER_1
1173 @item GPG_ERR_USER_2
1174 @item ...
1175 @item GPG_ERR_USER_16
1176 These error codes are not used by any GnuPG component and can be
1177 freely used by other software.  Applications using Libgcrypt
1178 might use them to mark specific errors returned by callback handlers
1179 if no suitable error codes (including the system errors) for these
1180 errors exist already.
1181 @end table
1182
1183
1184 @node Error Strings
1185 @subsection Error Strings
1186 @cindex error values, printing of
1187 @cindex error codes, printing of
1188 @cindex error sources, printing of
1189 @cindex error strings
1190
1191 @deftypefun {const char *} gcry_strerror (@w{gcry_error_t @var{err}})
1192 The function @code{gcry_strerror} returns a pointer to a statically
1193 allocated string containing a description of the error code contained
1194 in the error value @var{err}.  This string can be used to output a
1195 diagnostic message to the user.
1196 @end deftypefun
1197
1198
1199 @deftypefun {const char *} gcry_strsource (@w{gcry_error_t @var{err}})
1200 The function @code{gcry_strerror} returns a pointer to a statically
1201 allocated string containing a description of the error source
1202 contained in the error value @var{err}.  This string can be used to
1203 output a diagnostic message to the user.
1204 @end deftypefun
1205
1206 The following example illustrates the use of the functions described
1207 above:
1208
1209 @example
1210 @{
1211   gcry_cipher_hd_t handle;
1212   gcry_error_t err = 0;
1213
1214   err = gcry_cipher_open (&handle, GCRY_CIPHER_AES,
1215                           GCRY_CIPHER_MODE_CBC, 0);
1216   if (err)
1217     @{
1218       fprintf (stderr, "Failure: %s/%s\n",
1219                gcry_strsource (err),
1220                gcry_strerror (err));
1221     @}
1222 @}
1223 @end example
1224
1225 @c **********************************************************
1226 @c *******************  General  ****************************
1227 @c **********************************************************
1228 @node Handler Functions
1229 @chapter Handler Functions
1230
1231 Libgcrypt makes it possible to install so called `handler functions',
1232 which get called by Libgcrypt in case of certain events.
1233
1234 @menu
1235 * Progress handler::            Using a progress handler function.
1236 * Allocation handler::          Using special memory allocation functions.
1237 * Error handler::               Using error handler functions.
1238 * Logging handler::             Using a special logging function.
1239 @end menu
1240
1241 @node Progress handler
1242 @section Progress handler
1243
1244 It is often useful to retrieve some feedback while long running
1245 operations are performed.
1246
1247 @deftp {Data type} gcry_handler_progress_t
1248 Progress handler functions have to be of the type
1249 @code{gcry_handler_progress_t}, which is defined as:
1250
1251 @code{void (*gcry_handler_progress_t) (void *, const char *, int, int, int)}
1252 @end deftp
1253
1254 The following function may be used to register a handler function for
1255 this purpose.
1256
1257 @deftypefun void gcry_set_progress_handler (gcry_handler_progress_t @var{cb}, void *@var{cb_data})
1258
1259 This function installs @var{cb} as the `Progress handler' function.
1260 It may be used only during initialization.  @var{cb} must be defined
1261 as follows:
1262
1263 @example
1264 void
1265 my_progress_handler (void *@var{cb_data}, const char *@var{what},
1266                      int @var{printchar}, int @var{current}, int @var{total})
1267 @{
1268   /* Do something.  */
1269 @}
1270 @end example
1271
1272 A description of the arguments of the progress handler function follows.
1273
1274 @table @var
1275 @item cb_data
1276 The argument provided in the call to @code{gcry_set_progress_handler}.
1277 @item what
1278 A string identifying the type of the progress output.  The following
1279 values for @var{what} are defined:
1280
1281 @table @code
1282 @item need_entropy
1283 Not enough entropy is available.  @var{total} holds the number of
1284 required bytes.
1285
1286 @item primegen
1287 Values for @var{printchar}:
1288 @table @code
1289 @item \n
1290 Prime generated.
1291 @item !
1292 Need to refresh the pool of prime numbers.
1293 @item <, >
1294 Number of bits adjusted.
1295 @item ^
1296 Searching for a generator.
1297 @item .
1298 Fermat test on 10 candidates failed.
1299 @item :
1300 Restart with a new random value.
1301 @item +
1302 Rabin Miller test passed.
1303 @end table
1304
1305 @end table
1306
1307 @end table
1308 @end deftypefun
1309
1310 @node Allocation handler
1311 @section Allocation handler
1312
1313 It is possible to make Libgcrypt use special memory
1314 allocation functions instead of the built-in ones.
1315
1316 Memory allocation functions are of the following types:
1317 @deftp {Data type} gcry_handler_alloc_t
1318 This type is defined as: @code{void *(*gcry_handler_alloc_t) (size_t n)}.
1319 @end deftp
1320 @deftp {Data type} gcry_handler_secure_check_t
1321 This type is defined as: @code{int *(*gcry_handler_secure_check_t) (const void *)}.
1322 @end deftp
1323 @deftp {Data type} gcry_handler_realloc_t
1324 This type is defined as: @code{void *(*gcry_handler_realloc_t) (void *p, size_t n)}.
1325 @end deftp
1326 @deftp {Data type} gcry_handler_free_t
1327 This type is defined as: @code{void *(*gcry_handler_free_t) (void *)}.
1328 @end deftp
1329
1330 Special memory allocation functions can be installed with the
1331 following function:
1332
1333 @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})
1334 Install the provided functions and use them instead of the built-in
1335 functions for doing memory allocation.  Using this function is in
1336 general not recommended because the standard Libgcrypt allocation
1337 functions are guaranteed to zeroize memory if needed.
1338
1339 This function may be used only during initialization and may not be
1340 used in fips mode.
1341
1342
1343 @end deftypefun
1344
1345 @node Error handler
1346 @section Error handler
1347
1348 The following functions may be used to register handler functions that
1349 are called by Libgcrypt in case certain error conditions occur.  They
1350 may and should be registered prior to calling @code{gcry_check_version}.
1351
1352 @deftp {Data type} gcry_handler_no_mem_t
1353 This type is defined as: @code{int (*gcry_handler_no_mem_t) (void *, size_t, unsigned int)}
1354 @end deftp
1355 @deftypefun void gcry_set_outofcore_handler (gcry_handler_no_mem_t @var{func_no_mem}, void *@var{cb_data})
1356 This function registers @var{func_no_mem} as `out-of-core handler',
1357 which means that it will be called in the case of not having enough
1358 memory available.  The handler is called with 3 arguments: The first
1359 one is the pointer @var{cb_data} as set with this function, the second
1360 is the requested memory size and the last being a flag.  If bit 0 of
1361 the flag is set, secure memory has been requested.  The handler should
1362 either return true to indicate that Libgcrypt should try again
1363 allocating memory or return false to let Libgcrypt use its default
1364 fatal error handler.
1365 @end deftypefun
1366
1367 @deftp {Data type} gcry_handler_error_t
1368 This type is defined as: @code{void (*gcry_handler_error_t) (void *, int, const char *)}
1369 @end deftp
1370
1371 @deftypefun void gcry_set_fatalerror_handler (gcry_handler_error_t @var{func_error}, void *@var{cb_data})
1372 This function registers @var{func_error} as `error handler',
1373 which means that it will be called in error conditions.
1374 @end deftypefun
1375
1376 @node Logging handler
1377 @section Logging handler
1378
1379 @deftp {Data type} gcry_handler_log_t
1380 This type is defined as: @code{void (*gcry_handler_log_t) (void *, int, const char *, va_list)}
1381 @end deftp
1382
1383 @deftypefun void gcry_set_log_handler (gcry_handler_log_t @var{func_log}, void *@var{cb_data})
1384 This function registers @var{func_log} as `logging handler', which means
1385 that it will be called in case Libgcrypt wants to log a message.  This
1386 function may and should be used prior to calling
1387 @code{gcry_check_version}.
1388 @end deftypefun
1389
1390 @c **********************************************************
1391 @c *******************  Ciphers  ****************************
1392 @c **********************************************************
1393 @c @include cipher-ref.texi
1394 @node Symmetric cryptography
1395 @chapter Symmetric cryptography
1396
1397 The cipher functions are used for symmetrical cryptography,
1398 i.e. cryptography using a shared key.  The programming model follows
1399 an open/process/close paradigm and is in that similar to other
1400 building blocks provided by Libgcrypt.
1401
1402 @menu
1403 * Available ciphers::           List of ciphers supported by the library.
1404 * Cipher modules::              How to work with cipher modules.
1405 * Available cipher modes::      List of cipher modes supported by the library.
1406 * Working with cipher handles::  How to perform operations related to cipher handles.
1407 * General cipher functions::    General cipher functions independent of cipher handles.
1408 @end menu
1409
1410 @node Available ciphers
1411 @section Available ciphers
1412
1413 @table @code
1414 @item GCRY_CIPHER_NONE
1415 This is not a real algorithm but used by some functions as error return.
1416 The value always evaluates to false.
1417
1418 @item GCRY_CIPHER_IDEA
1419 @cindex IDEA
1420 This is the IDEA algorithm.  The constant is provided but there is
1421 currently no implementation for it because the algorithm is patented.
1422
1423 @item GCRY_CIPHER_3DES
1424 @cindex 3DES
1425 @cindex Triple-DES
1426 @cindex DES-EDE
1427 @cindex Digital Encryption Standard
1428 Triple-DES with 3 Keys as EDE.  The key size of this algorithm is 168 but
1429 you have to pass 192 bits because the most significant bits of each byte
1430 are ignored.
1431
1432 @item GCRY_CIPHER_CAST5
1433 @cindex CAST5
1434 CAST128-5 block cipher algorithm.  The key size is 128 bits.
1435
1436 @item GCRY_CIPHER_BLOWFISH
1437 @cindex Blowfish
1438 The blowfish algorithm. The current implementation allows only for a key
1439 size of 128 bits.
1440
1441 @item GCRY_CIPHER_SAFER_SK128
1442 Reserved and not currently implemented.
1443
1444 @item GCRY_CIPHER_DES_SK
1445 Reserved and not currently implemented.
1446
1447 @item  GCRY_CIPHER_AES
1448 @itemx GCRY_CIPHER_AES128
1449 @itemx GCRY_CIPHER_RIJNDAEL
1450 @itemx GCRY_CIPHER_RIJNDAEL128
1451 @cindex Rijndael
1452 @cindex AES
1453 @cindex Advanced Encryption Standard
1454 AES (Rijndael) with a 128 bit key.
1455
1456 @item  GCRY_CIPHER_AES192
1457 @itemx GCRY_CIPHER_RIJNDAEL192
1458 AES (Rijndael) with a 192 bit key.
1459
1460 @item  GCRY_CIPHER_AES256
1461 @itemx GCRY_CIPHER_RIJNDAEL256
1462 AES (Rijndael) with a 256 bit key.
1463
1464 @item  GCRY_CIPHER_TWOFISH
1465 @cindex Twofish
1466 The Twofish algorithm with a 256 bit key.
1467
1468 @item  GCRY_CIPHER_TWOFISH128
1469 The Twofish algorithm with a 128 bit key.
1470
1471 @item  GCRY_CIPHER_ARCFOUR
1472 @cindex Arcfour
1473 @cindex RC4
1474 An algorithm which is 100% compatible with RSA Inc.'s RC4 algorithm.
1475 Note that this is a stream cipher and must be used very carefully to
1476 avoid a couple of weaknesses.
1477
1478 @item  GCRY_CIPHER_DES
1479 @cindex DES
1480 Standard DES with a 56 bit key. You need to pass 64 bit but the high
1481 bits of each byte are ignored.  Note, that this is a weak algorithm
1482 which can be broken in reasonable time using a brute force approach.
1483
1484 @item  GCRY_CIPHER_SERPENT128
1485 @itemx GCRY_CIPHER_SERPENT192
1486 @itemx GCRY_CIPHER_SERPENT256
1487 @cindex Serpent
1488 The Serpent cipher from the AES contest.
1489
1490 @item  GCRY_CIPHER_RFC2268_40
1491 @itemx GCRY_CIPHER_RFC2268_128
1492 @cindex rfc-2268
1493 @cindex RC2
1494 Ron's Cipher 2 in the 40 and 128 bit variants.  Note, that we currently
1495 only support the 40 bit variant.  The identifier for 128 is reserved for
1496 future use.
1497
1498 @item GCRY_CIPHER_SEED
1499 @cindex Seed (cipher)
1500 A 128 bit cipher as described by RFC4269.
1501
1502 @item  GCRY_CIPHER_CAMELLIA128
1503 @itemx GCRY_CIPHER_CAMELLIA192
1504 @itemx GCRY_CIPHER_CAMELLIA256
1505 @cindex Camellia
1506 The Camellia cipher by NTT.  See
1507 @uref{http://info.isl.ntt.co.jp/@/crypt/@/eng/@/camellia/@/specifications.html}.
1508
1509 @end table
1510
1511 @node Cipher modules
1512 @section Cipher modules
1513
1514 Libgcrypt makes it possible to load additional `cipher modules'; these
1515 ciphers can be used just like the cipher algorithms that are built
1516 into the library directly.  For an introduction into extension
1517 modules, see @xref{Modules}.
1518
1519 @deftp {Data type} gcry_cipher_spec_t
1520 This is the `module specification structure' needed for registering
1521 cipher modules, which has to be filled in by the user before it can be
1522 used to register a module.  It contains the following members:
1523
1524 @table @code
1525 @item const char *name
1526 The primary name of the algorithm.
1527 @item const char **aliases
1528 A list of strings that are `aliases' for the algorithm.  The list must
1529 be terminated with a NULL element.
1530 @item gcry_cipher_oid_spec_t *oids
1531 A list of OIDs that are to be associated with the algorithm.  The
1532 list's last element must have it's `oid' member set to NULL.  See
1533 below for an explanation of this type.
1534 @item size_t blocksize
1535 The block size of the algorithm, in bytes.
1536 @item size_t keylen
1537 The length of the key, in bits.
1538 @item size_t contextsize
1539 The size of the algorithm-specific `context', that should be allocated
1540 for each handle.
1541 @item gcry_cipher_setkey_t setkey
1542 The function responsible for initializing a handle with a provided
1543 key.  See below for a description of this type.
1544 @item gcry_cipher_encrypt_t encrypt
1545 The function responsible for encrypting a single block.  See below for
1546 a description of this type.
1547 @item gcry_cipher_decrypt_t decrypt
1548 The function responsible for decrypting a single block.  See below for
1549 a description of this type.
1550 @item gcry_cipher_stencrypt_t stencrypt
1551 Like `encrypt', for stream ciphers.  See below for a description of
1552 this type.
1553 @item gcry_cipher_stdecrypt_t stdecrypt
1554 Like `decrypt', for stream ciphers.  See below for a description of
1555 this type.
1556 @end table
1557 @end deftp
1558
1559 @deftp {Data type} gcry_cipher_oid_spec_t
1560 This type is used for associating a user-provided algorithm
1561 implementation with certain OIDs.  It contains the following members:
1562 @table @code
1563 @item const char *oid
1564 Textual representation of the OID.
1565 @item int mode
1566 Cipher mode for which this OID is valid.
1567 @end table
1568 @end deftp
1569
1570 @deftp {Data type} gcry_cipher_setkey_t
1571 Type for the `setkey' function, defined as: gcry_err_code_t
1572 (*gcry_cipher_setkey_t) (void *c, const unsigned char *key, unsigned
1573 keylen)
1574 @end deftp
1575
1576 @deftp {Data type} gcry_cipher_encrypt_t
1577 Type for the `encrypt' function, defined as: gcry_err_code_t
1578 (*gcry_cipher_encrypt_t) (void *c, const unsigned char *outbuf, const
1579 unsigned char *inbuf)
1580 @end deftp
1581
1582 @deftp {Data type} gcry_cipher_decrypt_t
1583 Type for the `decrypt' function, defined as: gcry_err_code_t
1584 (*gcry_cipher_decrypt_t) (void *c, const unsigned char *outbuf, const
1585 unsigned char *inbuf)
1586 @end deftp
1587
1588 @deftp {Data type} gcry_cipher_stencrypt_t
1589 Type for the `stencrypt' function, defined as: gcry_err_code_t
1590 (*gcry_@/cipher_@/stencrypt_@/t) (void *c, const unsigned char *outbuf, const
1591 unsigned char *, unsigned int n)
1592 @end deftp
1593
1594 @deftp {Data type} gcry_cipher_stdecrypt_t
1595 Type for the `stdecrypt' function, defined as: gcry_err_code_t
1596 (*gcry_@/cipher_@/stdecrypt_@/t) (void *c, const unsigned char *outbuf, const
1597 unsigned char *, unsigned int n)
1598 @end deftp
1599
1600 @deftypefun gcry_error_t gcry_cipher_register (gcry_cipher_spec_t *@var{cipher}, unsigned int *algorithm_id, gcry_module_t *@var{module})
1601
1602 Register a new cipher module whose specification can be found in
1603 @var{cipher}.  On success, a new algorithm ID is stored in
1604 @var{algorithm_id} and a pointer representing this module is stored
1605 in @var{module}.  Deprecated; the module register interface will be
1606 removed in a future version.
1607 @end deftypefun
1608
1609 @deftypefun void gcry_cipher_unregister (gcry_module_t @var{module})
1610 Unregister the cipher identified by @var{module}, which must have been
1611 registered with gcry_cipher_register.
1612 @end deftypefun
1613
1614 @deftypefun gcry_error_t gcry_cipher_list (int *@var{list}, int *@var{list_length})
1615 Get a list consisting of the IDs of the loaded cipher modules.  If
1616 @var{list} is zero, write the number of loaded cipher modules to
1617 @var{list_length} and return.  If @var{list} is non-zero, the first
1618 *@var{list_length} algorithm IDs are stored in @var{list}, which must
1619 be of according size.  In case there are less cipher modules than
1620 *@var{list_length}, *@var{list_length} is updated to the correct
1621 number.
1622 @end deftypefun
1623
1624 @node Available cipher modes
1625 @section Available cipher modes
1626
1627 @table @code
1628 @item GCRY_CIPHER_MODE_NONE
1629 No mode specified.  This should not be used.  The only exception is that
1630 if Libgcrypt is not used in FIPS mode and if any debug flag has been
1631 set, this mode may be used to bypass the actual encryption.
1632
1633 @item GCRY_CIPHER_MODE_ECB
1634 @cindex ECB, Electronic Codebook mode
1635 Electronic Codebook mode.
1636
1637 @item GCRY_CIPHER_MODE_CFB
1638 @cindex CFB, Cipher Feedback mode
1639 Cipher Feedback mode.  The shift size equals the block size of the
1640 cipher (e.g. for AES it is CFB-128).
1641
1642 @item  GCRY_CIPHER_MODE_CBC
1643 @cindex CBC, Cipher Block Chaining mode
1644 Cipher Block Chaining mode.
1645
1646 @item GCRY_CIPHER_MODE_STREAM
1647 Stream mode, only to be used with stream cipher algorithms.
1648
1649 @item GCRY_CIPHER_MODE_OFB
1650 @cindex OFB, Output Feedback mode
1651 Output Feedback mode.
1652
1653 @item  GCRY_CIPHER_MODE_CTR
1654 @cindex CTR, Counter mode
1655 Counter mode.
1656
1657 @item  GCRY_CIPHER_MODE_AESWRAP
1658 @cindex AES-Wrap mode
1659 This mode is used to implement the AES-Wrap algorithm according to
1660 RFC-3394.  It may be used with any 128 bit block length algorithm,
1661 however the specs require one of the 3 AES algorithms.  These special
1662 conditions apply: If @code{gcry_cipher_setiv} has not been used the
1663 standard IV is used; if it has been used the lower 64 bit of the IV
1664 are used as the Alternative Initial Value.  On encryption the provided
1665 output buffer must be 64 bit (8 byte) larger than the input buffer;
1666 in-place encryption is still allowed.  On decryption the output buffer
1667 may be specified 64 bit (8 byte) shorter than then input buffer.  As
1668 per specs the input length must be at least 128 bits and the length
1669 must be a multiple of 64 bits.
1670
1671 @end table
1672
1673 @node Working with cipher handles
1674 @section Working with cipher handles
1675
1676 To use a cipher algorithm, you must first allocate an according
1677 handle.  This is to be done using the open function:
1678
1679 @deftypefun gcry_error_t gcry_cipher_open (gcry_cipher_hd_t *@var{hd}, int @var{algo}, int @var{mode}, unsigned int @var{flags})
1680
1681 This function creates the context handle required for most of the
1682 other cipher functions and returns a handle to it in `hd'.  In case of
1683 an error, an according error code is returned.
1684
1685 The ID of algorithm to use must be specified via @var{algo}.  See
1686 @xref{Available ciphers}, for a list of supported ciphers and the
1687 according constants.
1688
1689 Besides using the constants directly, the function
1690 @code{gcry_cipher_map_name} may be used to convert the textual name of
1691 an algorithm into the according numeric ID.
1692
1693 The cipher mode to use must be specified via @var{mode}.  See
1694 @xref{Available cipher modes}, for a list of supported cipher modes
1695 and the according constants.  Note that some modes are incompatible
1696 with some algorithms - in particular, stream mode
1697 (@code{GCRY_CIPHER_MODE_STREAM}) only works with stream ciphers. Any
1698 block cipher mode (@code{GCRY_CIPHER_MODE_ECB},
1699 @code{GCRY_CIPHER_MODE_CBC}, @code{GCRY_CIPHER_MODE_CFB},
1700 @code{GCRY_CIPHER_MODE_OFB} or @code{GCRY_CIPHER_MODE_CTR}) will work
1701 with any block cipher algorithm.
1702
1703 The third argument @var{flags} can either be passed as @code{0} or as
1704 the bit-wise OR of the following constants.
1705
1706 @table @code
1707 @item GCRY_CIPHER_SECURE
1708 Make sure that all operations are allocated in secure memory.  This is
1709 useful when the key material is highly confidential.
1710 @item GCRY_CIPHER_ENABLE_SYNC
1711 @cindex sync mode (OpenPGP)
1712 This flag enables the CFB sync mode, which is a special feature of
1713 Libgcrypt's CFB mode implementation to allow for OpenPGP's CFB variant.
1714 See @code{gcry_cipher_sync}.
1715 @item GCRY_CIPHER_CBC_CTS
1716 @cindex cipher text stealing
1717 Enable cipher text stealing (CTS) for the CBC mode.  Cannot be used
1718 simultaneous as GCRY_CIPHER_CBC_MAC.  CTS mode makes it possible to
1719 transform data of almost arbitrary size (only limitation is that it
1720 must be greater than the algorithm's block size).
1721 @item GCRY_CIPHER_CBC_MAC
1722 @cindex CBC-MAC
1723 Compute CBC-MAC keyed checksums.  This is the same as CBC mode, but
1724 only output the last block.  Cannot be used simultaneous as
1725 GCRY_CIPHER_CBC_CTS.
1726 @end table
1727 @end deftypefun
1728
1729 Use the following function to release an existing handle:
1730
1731 @deftypefun void gcry_cipher_close (gcry_cipher_hd_t @var{h})
1732
1733 This function releases the context created by @code{gcry_cipher_open}.
1734 It also zeroises all sensitive information associated with this cipher
1735 handle.
1736 @end deftypefun
1737
1738 In order to use a handle for performing cryptographic operations, a
1739 `key' has to be set first:
1740
1741 @deftypefun gcry_error_t gcry_cipher_setkey (gcry_cipher_hd_t @var{h}, const void *@var{k}, size_t @var{l})
1742
1743 Set the key @var{k} used for encryption or decryption in the context
1744 denoted by the handle @var{h}.  The length @var{l} (in bytes) of the
1745 key @var{k} must match the required length of the algorithm set for
1746 this context or be in the allowed range for algorithms with variable
1747 key size.  The function checks this and returns an error if there is a
1748 problem.  A caller should always check for an error.
1749
1750 @end deftypefun
1751
1752 Most crypto modes requires an initialization vector (IV), which
1753 usually is a non-secret random string acting as a kind of salt value.
1754 The CTR mode requires a counter, which is also similar to a salt
1755 value.  To set the IV or CTR, use these functions:
1756
1757 @deftypefun gcry_error_t gcry_cipher_setiv (gcry_cipher_hd_t @var{h}, const void *@var{k}, size_t @var{l})
1758
1759 Set the initialization vector used for encryption or decryption. The
1760 vector is passed as the buffer @var{K} of length @var{l} bytes and
1761 copied to internal data structures.  The function checks that the IV
1762 matches the requirement of the selected algorithm and mode.
1763 @end deftypefun
1764
1765 @deftypefun gcry_error_t gcry_cipher_setctr (gcry_cipher_hd_t @var{h}, const void *@var{c}, size_t @var{l})
1766
1767 Set the counter vector used for encryption or decryption. The counter
1768 is passed as the buffer @var{c} of length @var{l} bytes and copied to
1769 internal data structures.  The function checks that the counter
1770 matches the requirement of the selected algorithm (i.e., it must be
1771 the same size as the block size).
1772 @end deftypefun
1773
1774 @deftypefun gcry_error_t gcry_cipher_reset (gcry_cipher_hd_t @var{h})
1775
1776 Set the given handle's context back to the state it had after the last
1777 call to gcry_cipher_setkey and clear the initialization vector.
1778
1779 Note that gcry_cipher_reset is implemented as a macro.
1780 @end deftypefun
1781
1782 The actual encryption and decryption is done by using one of the
1783 following functions.  They may be used as often as required to process
1784 all the data.
1785
1786 @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})
1787
1788 @code{gcry_cipher_encrypt} is used to encrypt the data.  This function
1789 can either work in place or with two buffers.  It uses the cipher
1790 context already setup and described by the handle @var{h}.  There are 2
1791 ways to use the function: If @var{in} is passed as @code{NULL} and
1792 @var{inlen} is @code{0}, in-place encryption of the data in @var{out} or
1793 length @var{outsize} takes place.  With @var{in} being not @code{NULL},
1794 @var{inlen} bytes are encrypted to the buffer @var{out} which must have
1795 at least a size of @var{inlen}.  @var{outsize} must be set to the
1796 allocated size of @var{out}, so that the function can check that there
1797 is sufficient space. Note that overlapping buffers are not allowed.
1798
1799 Depending on the selected algorithms and encryption mode, the length of
1800 the buffers must be a multiple of the block size.
1801
1802 The function returns @code{0} on success or an error code.
1803 @end deftypefun
1804
1805
1806 @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})
1807
1808 @code{gcry_cipher_decrypt} is used to decrypt the data.  This function
1809 can either work in place or with two buffers.  It uses the cipher
1810 context already setup and described by the handle @var{h}.  There are 2
1811 ways to use the function: If @var{in} is passed as @code{NULL} and
1812 @var{inlen} is @code{0}, in-place decryption of the data in @var{out} or
1813 length @var{outsize} takes place.  With @var{in} being not @code{NULL},
1814 @var{inlen} bytes are decrypted to the buffer @var{out} which must have
1815 at least a size of @var{inlen}.  @var{outsize} must be set to the
1816 allocated size of @var{out}, so that the function can check that there
1817 is sufficient space.  Note that overlapping buffers are not allowed.
1818
1819 Depending on the selected algorithms and encryption mode, the length of
1820 the buffers must be a multiple of the block size.
1821
1822 The function returns @code{0} on success or an error code.
1823 @end deftypefun
1824
1825
1826 OpenPGP (as defined in RFC-2440) requires a special sync operation in
1827 some places.  The following function is used for this:
1828
1829 @deftypefun gcry_error_t gcry_cipher_sync (gcry_cipher_hd_t @var{h})
1830
1831 Perform the OpenPGP sync operation on context @var{h}.  Note that this
1832 is a no-op unless the context was created with the flag
1833 @code{GCRY_CIPHER_ENABLE_SYNC}
1834 @end deftypefun
1835
1836 Some of the described functions are implemented as macros utilizing a
1837 catch-all control function.  This control function is rarely used
1838 directly but there is nothing which would inhibit it:
1839
1840 @deftypefun gcry_error_t gcry_cipher_ctl (gcry_cipher_hd_t @var{h}, int @var{cmd}, void *@var{buffer}, size_t @var{buflen})
1841
1842 @code{gcry_cipher_ctl} controls various aspects of the cipher module and
1843 specific cipher contexts.  Usually some more specialized functions or
1844 macros are used for this purpose.  The semantics of the function and its
1845 parameters depends on the the command @var{cmd} and the passed context
1846 handle @var{h}.  Please see the comments in the source code
1847 (@code{src/global.c}) for details.
1848 @end deftypefun
1849
1850 @deftypefun gcry_error_t gcry_cipher_info (gcry_cipher_hd_t @var{h}, int @var{what}, void *@var{buffer}, size_t *@var{nbytes})
1851
1852 @code{gcry_cipher_info} is used to retrieve various
1853 information about a cipher context or the cipher module in general.
1854
1855 Currently no information is available.
1856 @end deftypefun
1857
1858 @node General cipher functions
1859 @section General cipher functions
1860
1861 To work with the algorithms, several functions are available to map
1862 algorithm names to the internal identifiers, as well as ways to
1863 retrieve information about an algorithm or the current cipher context.
1864
1865 @deftypefun gcry_error_t gcry_cipher_algo_info (int @var{algo}, int @var{what}, void *@var{buffer}, size_t *@var{nbytes})
1866
1867 This function is used to retrieve information on a specific algorithm.
1868 You pass the cipher algorithm ID as @var{algo} and the type of
1869 information requested as @var{what}. The result is either returned as
1870 the return code of the function or copied to the provided @var{buffer}
1871 whose allocated length must be available in an integer variable with the
1872 address passed in @var{nbytes}.  This variable will also receive the
1873 actual used length of the buffer.
1874
1875 Here is a list of supported codes for @var{what}:
1876
1877 @c begin constants for gcry_cipher_algo_info
1878 @table @code
1879 @item GCRYCTL_GET_KEYLEN:
1880 Return the length of the key. If the algorithm supports multiple key
1881 lengths, the maximum supported value is returned.  The length is
1882 returned as number of octets (bytes) and not as number of bits in
1883 @var{nbytes}; @var{buffer} must be zero.
1884
1885 @item GCRYCTL_GET_BLKLEN:
1886 Return the block length of the algorithm.  The length is returned as a
1887 number of octets in @var{nbytes}; @var{buffer} must be zero.
1888
1889 @item GCRYCTL_TEST_ALGO:
1890 Returns @code{0} when the specified algorithm is available for use.
1891 @var{buffer} and @var{nbytes} must be zero.
1892
1893 @end table
1894 @c end constants for gcry_cipher_algo_info
1895
1896 @end deftypefun
1897 @c end gcry_cipher_algo_info
1898
1899 @deftypefun {const char *} gcry_cipher_algo_name (int @var{algo})
1900
1901 @code{gcry_cipher_algo_name} returns a string with the name of the
1902 cipher algorithm @var{algo}.  If the algorithm is not known or another
1903 error occurred, the string @code{"?"} is returned.  This function should
1904 not be used to test for the availability of an algorithm.
1905 @end deftypefun
1906
1907 @deftypefun int gcry_cipher_map_name (const char *@var{name})
1908
1909 @code{gcry_cipher_map_name} returns the algorithm identifier for the
1910 cipher algorithm described by the string @var{name}.  If this algorithm
1911 is not available @code{0} is returned.
1912 @end deftypefun
1913
1914 @deftypefun int gcry_cipher_mode_from_oid (const char *@var{string})
1915
1916 Return the cipher mode associated with an @acronym{ASN.1} object
1917 identifier.  The object identifier is expected to be in the
1918 @acronym{IETF}-style dotted decimal notation.  The function returns
1919 @code{0} for an unknown object identifier or when no mode is associated
1920 with it.
1921 @end deftypefun
1922
1923
1924 @c **********************************************************
1925 @c *******************  Public Key  *************************
1926 @c **********************************************************
1927 @node Public Key cryptography
1928 @chapter Public Key cryptography
1929
1930 Public key cryptography, also known as asymmetric cryptography, is an
1931 easy way for key management and to provide digital signatures.
1932 Libgcrypt provides two completely different interfaces to
1933 public key cryptography, this chapter explains the one based on
1934 S-expressions.
1935
1936 @menu
1937 * Available algorithms::        Algorithms supported by the library.
1938 * Used S-expressions::          Introduction into the used S-expression.
1939 * Public key modules::          How to work with public key modules.
1940 * Cryptographic Functions::     Functions for performing the cryptographic actions.
1941 * General public-key related Functions::  General functions, not implementing any cryptography.
1942
1943 * AC Interface::                Alternative interface to public key functions.
1944 @end menu
1945
1946 @node Available algorithms
1947 @section Available algorithms
1948
1949 Libgcrypt supports the RSA (Rivest-Shamir-Adleman) algorithms as well
1950 as DSA (Digital Signature Algorithm) and Elgamal.  The versatile
1951 interface allows to add more algorithms in the future.
1952
1953 @node Used S-expressions
1954 @section Used S-expressions
1955
1956 Libgcrypt's API for asymmetric cryptography is based on data structures
1957 called S-expressions (see
1958 @uref{http://people.csail.mit.edu/@/rivest/@/sexp.html}) and does not work
1959 with contexts as most of the other building blocks of Libgcrypt do.
1960
1961 @noindent
1962 The following information are stored in S-expressions:
1963
1964 @itemize @asis
1965 @item keys
1966
1967 @item plain text data
1968
1969 @item encrypted data
1970
1971 @item signatures
1972
1973 @end itemize
1974
1975 @noindent
1976 To describe how Libgcrypt expect keys, we use examples. Note that
1977 words in
1978 @ifnottex
1979 uppercase
1980 @end ifnottex
1981 @iftex
1982 italics
1983 @end iftex
1984 indicate parameters whereas lowercase words are literals.
1985
1986 Note that all MPI (multi-precision-integers) values are expected to be in
1987 @code{GCRYMPI_FMT_USG} format.  An easy way to create S-expressions is
1988 by using @code{gcry_sexp_build} which allows to pass a string with
1989 printf-like escapes to insert MPI values.
1990
1991 @menu
1992 * RSA key parameters::  Parameters used with an RSA key.
1993 * DSA key parameters::  Parameters used with a DSA key.
1994 * ECC key parameters::  Parameters used with ECC keys.
1995 @end menu
1996
1997 @node RSA key parameters
1998 @subsection RSA key parameters
1999
2000 @noindent
2001 An RSA private key is described by this S-expression:
2002
2003 @example
2004 (private-key
2005   (rsa
2006     (n @var{n-mpi})
2007     (e @var{e-mpi})
2008     (d @var{d-mpi})
2009     (p @var{p-mpi})
2010     (q @var{q-mpi})
2011     (u @var{u-mpi})))
2012 @end example
2013
2014 @noindent
2015 An RSA public key is described by this S-expression:
2016
2017 @example
2018 (public-key
2019   (rsa
2020     (n @var{n-mpi})
2021     (e @var{e-mpi})))
2022 @end example
2023
2024
2025 @table @var
2026 @item n-mpi
2027 RSA public modulus @math{n}.
2028 @item e-mpi
2029 RSA public exponent @math{e}.
2030 @item d-mpi
2031 RSA secret exponent @math{d = e^{-1} \bmod (p-1)(q-1)}.
2032 @item p-mpi
2033 RSA secret prime @math{p}.
2034 @item q-mpi
2035 RSA secret prime @math{q} with @math{p < q}.
2036 @item u-mpi
2037 Multiplicative inverse @math{u = p^{-1} \bmod q}.
2038 @end table
2039
2040 For signing and decryption the parameters @math{(p, q, u)} are optional
2041 but greatly improve the performance.  Either all of these optional
2042 parameters must be given or none of them.  They are mandatory for
2043 gcry_pk_testkey.
2044
2045 Note that OpenSSL uses slighly different parameters: @math{q < p} and
2046  @math{u = q^{-1} \bmod p}.  To use these parameters you will need to
2047 swap the values and recompute @math{u}.  Here is example code to do this:
2048
2049 @example
2050   if (gcry_mpi_cmp (p, q) > 0)
2051     @{
2052       gcry_mpi_swap (p, q);
2053       gcry_mpi_invm (u, p, q);
2054     @}
2055 @end example
2056
2057
2058
2059
2060 @node DSA key parameters
2061 @subsection DSA key parameters
2062
2063 @noindent
2064 A DSA private key is described by this S-expression:
2065
2066 @example
2067 (private-key
2068   (dsa
2069     (p @var{p-mpi})
2070     (q @var{q-mpi})
2071     (g @var{g-mpi})
2072     (y @var{y-mpi})
2073     (x @var{x-mpi})))
2074 @end example
2075
2076 @table @var
2077 @item p-mpi
2078 DSA prime @math{p}.
2079 @item q-mpi
2080 DSA group order @math{q} (which is a prime divisor of @math{p-1}).
2081 @item g-mpi
2082 DSA group generator @math{g}.
2083 @item y-mpi
2084 DSA public key value @math{y = g^x \bmod p}.
2085 @item x-mpi
2086 DSA secret exponent x.
2087 @end table
2088
2089 The public key is similar with "private-key" replaced by "public-key"
2090 and no @var{x-mpi}.
2091
2092
2093 @node ECC key parameters
2094 @subsection ECC key parameters
2095
2096 @noindent
2097 An ECC private key is described by this S-expression:
2098
2099 @example
2100 (private-key
2101   (ecc
2102     (p @var{p-mpi})
2103     (a @var{a-mpi})
2104     (b @var{b-mpi})
2105     (g @var{g-point})
2106     (n @var{n-mpi})
2107     (q @var{q-point})
2108     (d @var{d-mpi})))
2109 @end example
2110
2111 @table @var
2112 @item p-mpi
2113 Prime specifying the field @math{GF(p)}.
2114 @item a-mpi
2115 @itemx b-mpi
2116 The two coefficients of the Weierstrass equation @math{y^2 = x^3 + ax + b}
2117 @item g-point
2118 Base point @math{g}.
2119 @item n-mpi
2120 Order of @math{g}
2121 @item q-point
2122 The point representing the public key @math{Q = dP}.
2123 @item d-mpi
2124 The private key @math{d}
2125 @end table
2126
2127 All point values are encoded in standard format; Libgcrypt does
2128 currently only support uncompressed points, thus the first byte needs to
2129 be @code{0x04}.
2130
2131 The public key is similar with "private-key" replaced by "public-key"
2132 and no @var{d-mpi}.
2133
2134 If the domain parameters are well-known, the name of this curve may be
2135 used.  For example
2136
2137 @example
2138 (private-key
2139   (ecc
2140     (curve "NIST P-192")
2141     (q @var{q-point})
2142     (d @var{d-mpi})))
2143 @end example
2144
2145 The @code{curve} parameter may be given in any case and is used to replace
2146 missing parameters.
2147
2148 @noindent
2149 Currently implemented curves are:
2150 @table @code
2151 @item NIST P-192
2152 @itemx 1.2.840.10045.3.1.1
2153 @itemx prime192v1
2154 @itemx secp192r1
2155 The NIST 192 bit curve, its OID, X9.62 and SECP aliases.
2156
2157 @item NIST P-224
2158 @itemx secp224r1
2159 The NIST 224 bit curve and its SECP alias.
2160
2161 @item NIST P-256
2162 @itemx 1.2.840.10045.3.1.7
2163 @itemx prime256v1
2164 @itemx secp256r1
2165 The NIST 256 bit curve, its OID, X9.62 and SECP aliases.
2166
2167 @item NIST P-384
2168 @itemx secp384r1
2169 The NIST 384 bit curve and its SECP alias.
2170
2171 @item NIST P-521
2172 @itemx secp521r1
2173 The NIST 521 bit curve and its SECP alias.
2174
2175 @end table
2176 As usual the OIDs may optionally be prefixed with the string @code{OID.}
2177 or @code{oid.}.
2178
2179
2180
2181 @node Public key modules
2182 @section Public key modules
2183
2184 Libgcrypt makes it possible to load additional `public key
2185 modules'; these public key algorithms can be used just like the
2186 algorithms that are built into the library directly.  For an
2187 introduction into extension modules, see @xref{Modules}.
2188
2189 @deftp {Data type} gcry_pk_spec_t
2190 This is the `module specification structure' needed for registering
2191 public key modules, which has to be filled in by the user before it
2192 can be used to register a module.  It contains the following members:
2193
2194 @table @code
2195 @item const char *name
2196 The primary name of this algorithm.
2197 @item char **aliases
2198 A list of strings that are `aliases' for the algorithm.  The list
2199 must be terminated with a NULL element.
2200 @item const char *elements_pkey
2201 String containing the one-letter names of the MPI values contained in
2202 a public key.
2203 @item const char *element_skey
2204 String containing the one-letter names of the MPI values contained in
2205 a secret key.
2206 @item const char *elements_enc
2207 String containing the one-letter names of the MPI values that are the
2208 result of an encryption operation using this algorithm.
2209 @item const char *elements_sig
2210 String containing the one-letter names of the MPI values that are the
2211 result of a sign operation using this algorithm.
2212 @item const char *elements_grip
2213 String containing the one-letter names of the MPI values that are to
2214 be included in the `key grip'.
2215 @item int use
2216 The bitwise-OR of the following flags, depending on the abilities of
2217 the algorithm:
2218 @table @code
2219 @item GCRY_PK_USAGE_SIGN
2220 The algorithm supports signing and verifying of data.
2221 @item GCRY_PK_USAGE_ENCR
2222 The algorithm supports the encryption and decryption of data.
2223 @end table
2224 @item gcry_pk_generate_t generate
2225 The function responsible for generating a new key pair.  See below for
2226 a description of this type.
2227 @item gcry_pk_check_secret_key_t check_secret_key
2228 The function responsible for checking the sanity of a provided secret
2229 key.  See below for a description of this type.
2230 @item gcry_pk_encrypt_t encrypt
2231 The function responsible for encrypting data.  See below for a
2232 description of this type.
2233 @item gcry_pk_decrypt_t decrypt
2234 The function responsible for decrypting data.  See below for a
2235 description of this type.
2236 @item gcry_pk_sign_t sign
2237 The function responsible for signing data.  See below for a description
2238 of this type.
2239 @item gcry_pk_verify_t verify
2240 The function responsible for verifying that the provided signature
2241 matches the provided data.  See below for a description of this type.
2242 @item gcry_pk_get_nbits_t get_nbits
2243 The function responsible for returning the number of bits of a provided
2244 key.  See below for a description of this type.
2245 @end table
2246 @end deftp
2247
2248 @deftp {Data type} gcry_pk_generate_t
2249 Type for the `generate' function, defined as: gcry_err_code_t
2250 (*gcry_pk_generate_t) (int algo, unsigned int nbits, unsigned long
2251 use_e, gcry_mpi_t *skey, gcry_mpi_t **retfactors)
2252 @end deftp
2253
2254 @deftp {Data type} gcry_pk_check_secret_key_t
2255 Type for the `check_secret_key' function, defined as: gcry_err_code_t
2256 (*gcry_pk_check_secret_key_t) (int algo, gcry_mpi_t *skey)
2257 @end deftp
2258
2259 @deftp {Data type} gcry_pk_encrypt_t
2260 Type for the `encrypt' function, defined as: gcry_err_code_t
2261 (*gcry_pk_encrypt_t) (int algo, gcry_mpi_t *resarr, gcry_mpi_t data,
2262 gcry_mpi_t *pkey, int flags)
2263 @end deftp
2264
2265 @deftp {Data type} gcry_pk_decrypt_t
2266 Type for the `decrypt' function, defined as: gcry_err_code_t
2267 (*gcry_pk_decrypt_t) (int algo, gcry_mpi_t *result, gcry_mpi_t *data,
2268 gcry_mpi_t *skey, int flags)
2269 @end deftp
2270
2271 @deftp {Data type} gcry_pk_sign_t
2272 Type for the `sign' function, defined as: gcry_err_code_t
2273 (*gcry_pk_sign_t) (int algo, gcry_mpi_t *resarr, gcry_mpi_t data,
2274 gcry_mpi_t *skey)
2275 @end deftp
2276
2277 @deftp {Data type} gcry_pk_verify_t
2278 Type for the `verify' function, defined as: gcry_err_code_t
2279 (*gcry_pk_verify_t) (int algo, gcry_mpi_t hash, gcry_mpi_t *data,
2280 gcry_mpi_t *pkey, int (*cmp) (void *, gcry_mpi_t), void *opaquev)
2281 @end deftp
2282
2283 @deftp {Data type} gcry_pk_get_nbits_t
2284 Type for the `get_nbits' function, defined as: unsigned
2285 (*gcry_pk_get_nbits_t) (int algo, gcry_mpi_t *pkey)
2286 @end deftp
2287
2288 @deftypefun gcry_error_t gcry_pk_register (gcry_pk_spec_t *@var{pubkey}, unsigned int *algorithm_id, gcry_module_t *@var{module})
2289
2290 Register a new public key module whose specification can be found in
2291 @var{pubkey}.  On success, a new algorithm ID is stored in
2292 @var{algorithm_id} and a pointer representing this module is stored in
2293 @var{module}.  Deprecated; the module register interface will be
2294 removed in a future version.
2295
2296 @end deftypefun
2297
2298 @deftypefun void gcry_pk_unregister (gcry_module_t @var{module})
2299 Unregister the public key module identified by @var{module}, which
2300 must have been registered with gcry_pk_register.
2301 @end deftypefun
2302
2303 @deftypefun gcry_error_t gcry_pk_list (int *@var{list}, int *@var{list_length})
2304 Get a list consisting of the IDs of the loaded pubkey modules.  If
2305 @var{list} is zero, write the number of loaded pubkey modules to
2306 @var{list_length} and return.  If @var{list} is non-zero, the first
2307 *@var{list_length} algorithm IDs are stored in @var{list}, which must
2308 be of according size.  In case there are less pubkey modules than
2309 *@var{list_length}, *@var{list_length} is updated to the correct
2310 number.
2311 @end deftypefun
2312
2313 @node Cryptographic Functions
2314 @section Cryptographic Functions
2315
2316 @noindent
2317 Note that we will in future allow to use keys without p,q and u
2318 specified and may also support other parameters for performance
2319 reasons.
2320
2321 @noindent
2322
2323 Some functions operating on S-expressions support `flags', that
2324 influence the operation.  These flags have to be listed in a
2325 sub-S-expression named `flags'; the following flags are known:
2326
2327 @table @code
2328 @item pkcs1
2329 Use PKCS#1 block type 2 padding.
2330 @item no-blinding
2331 Do not use a technique called `blinding', which is used by default in
2332 order to prevent leaking of secret information.  Blinding is only
2333 implemented by RSA, but it might be implemented by other algorithms in
2334 the future as well, when necessary.
2335 @end table
2336
2337 @noindent
2338 Now that we know the key basics, we can carry on and explain how to
2339 encrypt and decrypt data.  In almost all cases the data is a random
2340 session key which is in turn used for the actual encryption of the real
2341 data.  There are 2 functions to do this:
2342
2343 @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}})
2344
2345 Obviously a public key must be provided for encryption.  It is
2346 expected as an appropriate S-expression (see above) in @var{pkey}.
2347 The data to be encrypted can either be in the simple old format, which
2348 is a very simple S-expression consisting only of one MPI, or it may be
2349 a more complex S-expression which also allows to specify flags for
2350 operation, like e.g. padding rules.
2351
2352 @noindent
2353 If you don't want to let Libgcrypt handle the padding, you must pass an
2354 appropriate MPI using this expression for @var{data}:
2355
2356 @example
2357 (data
2358   (flags raw)
2359   (value @var{mpi}))
2360 @end example
2361
2362 @noindent
2363 This has the same semantics as the old style MPI only way.  @var{MPI} is
2364 the actual data, already padded appropriate for your protocol.  Most
2365 systems however use PKCS#1 padding and so you can use this S-expression
2366 for @var{data}:
2367
2368 @example
2369 (data
2370   (flags pkcs1)
2371   (value @var{block}))
2372 @end example
2373
2374 @noindent
2375 Here, the "flags" list has the "pkcs1" flag which let the function know
2376 that it should provide PKCS#1 block type 2 padding.  The actual data to
2377 be encrypted is passed as a string of octets in @var{block}.  The
2378 function checks that this data actually can be used with the given key,
2379 does the padding and encrypts it.
2380
2381 If the function could successfully perform the encryption, the return
2382 value will be 0 and a new S-expression with the encrypted result is
2383 allocated and assigned to the variable at the address of @var{r_ciph}.
2384 The caller is responsible to release this value using
2385 @code{gcry_sexp_release}.  In case of an error, an error code is
2386 returned and @var{r_ciph} will be set to @code{NULL}.
2387
2388 @noindent
2389 The returned S-expression has this format when used with RSA:
2390
2391 @example
2392 (enc-val
2393   (rsa
2394     (a @var{a-mpi})))
2395 @end example
2396
2397 @noindent
2398 Where @var{a-mpi} is an MPI with the result of the RSA operation.  When
2399 using the Elgamal algorithm, the return value will have this format:
2400
2401 @example
2402 (enc-val
2403   (elg
2404     (a @var{a-mpi})
2405     (b @var{b-mpi})))
2406 @end example
2407
2408 @noindent
2409 Where @var{a-mpi} and @var{b-mpi} are MPIs with the result of the
2410 Elgamal encryption operation.
2411 @end deftypefun
2412 @c end gcry_pk_encrypt
2413
2414 @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}})
2415
2416 Obviously a private key must be provided for decryption.  It is expected
2417 as an appropriate S-expression (see above) in @var{skey}.  The data to
2418 be decrypted must match the format of the result as returned by
2419 @code{gcry_pk_encrypt}, but should be enlarged with a @code{flags}
2420 element:
2421
2422 @example
2423 (enc-val
2424   (flags)
2425   (elg
2426     (a @var{a-mpi})
2427     (b @var{b-mpi})))
2428 @end example
2429
2430 @noindent
2431 Note that this function currently does not know of any padding
2432 methods and the caller must do any un-padding on his own.
2433
2434 @noindent
2435 The function returns 0 on success or an error code.  The variable at the
2436 address of @var{r_plain} will be set to NULL on error or receive the
2437 decrypted value on success.  The format of @var{r_plain} is a
2438 simple S-expression part (i.e. not a valid one) with just one MPI if
2439 there was no @code{flags} element in @var{data}; if at least an empty
2440 @code{flags} is passed in @var{data}, the format is:
2441
2442 @example
2443 (value @var{plaintext})
2444 @end example
2445 @end deftypefun
2446 @c end gcry_pk_decrypt
2447
2448
2449 Another operation commonly performed using public key cryptography is
2450 signing data.  In some sense this is even more important than
2451 encryption because digital signatures are an important instrument for
2452 key management.  Libgcrypt supports digital signatures using
2453 2 functions, similar to the encryption functions:
2454
2455 @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}})
2456
2457 This function creates a digital signature for @var{data} using the
2458 private key @var{skey} and place it into the variable at the address of
2459 @var{r_sig}.  @var{data} may either be the simple old style S-expression
2460 with just one MPI or a modern and more versatile S-expression which
2461 allows to let Libgcrypt handle padding:
2462
2463 @example
2464  (data
2465   (flags pkcs1)
2466   (hash @var{hash-algo} @var{block}))
2467 @end example
2468
2469 @noindent
2470 This example requests to sign the data in @var{block} after applying
2471 PKCS#1 block type 1 style padding.  @var{hash-algo} is a string with the
2472 hash algorithm to be encoded into the signature, this may be any hash
2473 algorithm name as supported by Libgcrypt.  Most likely, this will be
2474 "sha256" or "sha1".  It is obvious that the length of @var{block} must
2475 match the size of that message digests; the function checks that this
2476 and other constraints are valid.
2477
2478 @noindent
2479 If PKCS#1 padding is not required (because the caller does already
2480 provide a padded value), either the old format or better the following
2481 format should be used:
2482
2483 @example
2484 (data
2485   (flags raw)
2486   (value @var{mpi}))
2487 @end example
2488
2489 @noindent
2490 Here, the data to be signed is directly given as an @var{MPI}.
2491
2492 @noindent
2493 The signature is returned as a newly allocated S-expression in
2494 @var{r_sig} using this format for RSA:
2495
2496 @example
2497 (sig-val
2498   (rsa
2499     (s @var{s-mpi})))
2500 @end example
2501
2502 Where @var{s-mpi} is the result of the RSA sign operation.  For DSA the
2503 S-expression returned is:
2504
2505 @example
2506 (sig-val
2507   (dsa
2508     (r @var{r-mpi})
2509     (s @var{s-mpi})))
2510 @end example
2511
2512 Where @var{r-mpi} and @var{s-mpi} are the result of the DSA sign
2513 operation.  For Elgamal signing (which is slow, yields large numbers
2514 and probably is not as secure as the other algorithms), the same format is
2515 used with "elg" replacing "dsa".
2516 @end deftypefun
2517 @c end gcry_pk_sign
2518
2519 @noindent
2520 The operation most commonly used is definitely the verification of a
2521 signature.  Libgcrypt provides this function:
2522
2523 @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}})
2524
2525 This is used to check whether the signature @var{sig} matches the
2526 @var{data}.  The public key @var{pkey} must be provided to perform this
2527 verification.  This function is similar in its parameters to
2528 @code{gcry_pk_sign} with the exceptions that the public key is used
2529 instead of the private key and that no signature is created but a
2530 signature, in a format as created by @code{gcry_pk_sign}, is passed to
2531 the function in @var{sig}.
2532
2533 @noindent
2534 The result is 0 for success (i.e. the data matches the signature), or an
2535 error code where the most relevant code is @code{GCRYERR_BAD_SIGNATURE}
2536 to indicate that the signature does not match the provided data.
2537
2538 @end deftypefun
2539 @c end gcry_pk_verify
2540
2541 @node General public-key related Functions
2542 @section General public-key related Functions
2543
2544 @noindent
2545 A couple of utility functions are available to retrieve the length of
2546 the key, map algorithm identifiers and perform sanity checks:
2547
2548 @deftypefun {const char *} gcry_pk_algo_name (int @var{algo})
2549
2550 Map the public key algorithm id @var{algo} to a string representation of
2551 the algorithm name.  For unknown algorithms this functions returns the
2552 string @code{"?"}.  This function should not be used to test for the
2553 availability of an algorithm.
2554 @end deftypefun
2555
2556 @deftypefun int gcry_pk_map_name (const char *@var{name})
2557
2558 Map the algorithm @var{name} to a public key algorithm Id.  Returns 0 if
2559 the algorithm name is not known.
2560 @end deftypefun
2561
2562 @deftypefun int gcry_pk_test_algo (int @var{algo})
2563
2564 Return 0 if the public key algorithm @var{algo} is available for use.
2565 Note that this is implemented as a macro.
2566 @end deftypefun
2567
2568
2569 @deftypefun {unsigned int} gcry_pk_get_nbits (gcry_sexp_t @var{key})
2570
2571 Return what is commonly referred as the key length for the given
2572 public or private in @var{key}.
2573 @end deftypefun
2574
2575 @deftypefun {unsigned char *} gcry_pk_get_keygrip (@w{gcry_sexp_t @var{key}}, @w{unsigned char *@var{array}})
2576
2577 Return the so called "keygrip" which is the SHA-1 hash of the public key
2578 parameters expressed in a way depended on the algorithm.  @var{array}
2579 must either provide space for 20 bytes or be @code{NULL}. In the latter
2580 case a newly allocated array of that size is returned.  On success a
2581 pointer to the newly allocated space or to @var{array} is returned.
2582 @code{NULL} is returned to indicate an error which is most likely an
2583 unknown algorithm or one where a "keygrip" has not yet been defined.
2584 The function accepts public or secret keys in @var{key}.
2585 @end deftypefun
2586
2587 @deftypefun gcry_error_t gcry_pk_testkey (gcry_sexp_t @var{key})
2588
2589 Return zero if the private key @var{key} is `sane', an error code otherwise.
2590 Note that it is not possible to check the `saneness' of a public key.
2591
2592 @end deftypefun
2593
2594
2595 @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}})
2596
2597 Depending on the value of @var{what} return various information about
2598 the public key algorithm with the id @var{algo}.  Note that the
2599 function returns @code{-1} on error and the actual error code must be
2600 retrieved using the function @code{gcry_errno}.  The currently defined
2601 values for @var{what} are:
2602
2603 @table @code
2604 @item GCRYCTL_TEST_ALGO:
2605 Return 0 if the specified algorithm is available for use.
2606 @var{buffer} must be @code{NULL}, @var{nbytes} may be passed as
2607 @code{NULL} or point to a variable with the required usage of the
2608 algorithm. This may be 0 for "don't care" or the bit-wise OR of these
2609 flags:
2610
2611 @table @code
2612 @item GCRY_PK_USAGE_SIGN
2613 Algorithm is usable for signing.
2614 @item GCRY_PK_USAGE_ENCR
2615 Algorithm is usable for encryption.
2616 @end table
2617
2618 Unless you need to test for the allowed usage, it is in general better
2619 to use the macro gcry_pk_test_algo instead.
2620
2621 @item GCRYCTL_GET_ALGO_USAGE:
2622 Return the usage flags for the given algorithm.  An invalid algorithm
2623 return 0.  Disabled algorithms are ignored here because we
2624 want to know whether the algorithm is at all capable of a certain usage.
2625
2626 @item GCRYCTL_GET_ALGO_NPKEY
2627 Return the number of elements the public key for algorithm @var{algo}
2628 consist of.  Return 0 for an unknown algorithm.
2629
2630 @item GCRYCTL_GET_ALGO_NSKEY
2631 Return the number of elements the private key for algorithm @var{algo}
2632 consist of.  Note that this value is always larger than that of the
2633 public key.  Return 0 for an unknown algorithm.
2634
2635 @item GCRYCTL_GET_ALGO_NSIGN
2636 Return the number of elements a signature created with the algorithm
2637 @var{algo} consists of.  Return 0 for an unknown algorithm or for an
2638 algorithm not capable of creating signatures.
2639
2640 @item GCRYCTL_GET_ALGO_NENC
2641 Return the number of elements a encrypted message created with the algorithm
2642 @var{algo} consists of.  Return 0 for an unknown algorithm or for an
2643 algorithm not capable of encryption.
2644 @end table
2645
2646 @noindent
2647 Please note that parameters not required should be passed as @code{NULL}.
2648 @end deftypefun
2649 @c end gcry_pk_algo_info
2650
2651
2652 @deftypefun gcry_error_t gcry_pk_ctl (@w{int @var{cmd}}, @w{void *@var{buffer}}, @w{size_t @var{buflen}})
2653
2654 This is a general purpose function to perform certain control
2655 operations.  @var{cmd} controls what is to be done. The return value is
2656 0 for success or an error code.  Currently supported values for
2657 @var{cmd} are:
2658
2659 @table @code
2660 @item GCRYCTL_DISABLE_ALGO
2661 Disable the algorithm given as an algorithm id in @var{buffer}.
2662 @var{buffer} must point to an @code{int} variable with the algorithm id
2663 and @var{buflen} must have the value @code{sizeof (int)}.
2664
2665 @end table
2666 @end deftypefun
2667 @c end gcry_pk_ctl
2668
2669 @noindent
2670 Libgcrypt also provides a function to generate public key
2671 pairs:
2672
2673 @deftypefun gcry_error_t gcry_pk_genkey (@w{gcry_sexp_t *@var{r_key}}, @w{gcry_sexp_t @var{parms}})
2674
2675 This function create a new public key pair using information given in
2676 the S-expression @var{parms} and stores the private and the public key
2677 in one new S-expression at the address given by @var{r_key}.  In case of
2678 an error, @var{r_key} is set to @code{NULL}.  The return code is 0 for
2679 success or an error code otherwise.
2680
2681 @noindent
2682 Here is an example for @var{parms} to create an 2048 bit RSA key:
2683
2684 @example
2685 (genkey
2686   (rsa
2687     (nbits 4:2048)))
2688 @end example
2689
2690 @noindent
2691 To create an Elgamal key, substitute "elg" for "rsa" and to create a DSA
2692 key use "dsa".  Valid ranges for the key length depend on the
2693 algorithms; all commonly used key lengths are supported.  Currently
2694 supported parameters are:
2695
2696 @table @code
2697 @item nbits
2698 This is always required to specify the length of the key.  The argument
2699 is a string with a number in C-notation.  The value should be a multiple
2700 of 8.
2701
2702 @item curve @var{name}
2703 For ECC a named curve may be used instead of giving the number of
2704 requested bits.  This allows to request a specific curve to override a
2705 default selection Libgcrypt would have taken if @code{nbits} has been
2706 given.  The available names are listed with the description of the ECC
2707 public key parameters.
2708
2709 @item rsa-use-e
2710 This is only used with RSA to give a hint for the public exponent. The
2711 value will be used as a base to test for a usable exponent. Some values
2712 are special:
2713
2714 @table @samp
2715 @item 0
2716 Use a secure and fast value.  This is currently the number 41.
2717 @item 1
2718 Use a value as required by some crypto policies.  This is currently
2719 the number 65537.
2720 @item 2
2721 Reserved
2722 @item > 2
2723 Use the given value.
2724 @end table
2725
2726 @noindent
2727 If this parameter is not used, Libgcrypt uses for historic reasons
2728 65537.
2729
2730 @item qbits
2731 This is only meanigful for DSA keys.  If it is given the DSA key is
2732 generated with a Q parameyer of this size.  If it is not given or zero
2733 Q is deduced from NBITS in this way:
2734 @table @samp
2735 @item 512 <= N <= 1024
2736 Q = 160
2737 @item N = 2048
2738 Q = 224
2739 @item N = 3072
2740 Q = 256
2741 @item N = 7680
2742 Q = 384
2743 @item N = 15360
2744 Q = 512
2745 @end table
2746 Note that in this case only the values for N, as given in the table,
2747 are allowed.  When specifying Q all values of N in the range 512 to
2748 15680 are valid as long as they are multiples of 8.
2749
2750 @item transient-key
2751 This is only meaningful for RSA, DSA, ECDSA, and ECDH keys.  This is a flag
2752 with no value.  If given the key is created using a faster and a
2753 somewhat less secure random number generator.  This flag may be used for
2754 keys which are only used for a short time or per-message and do not require full
2755 cryptographic strength.
2756
2757 @item domain
2758 This is only meaningful for DLP algorithms.  If specified keys are
2759 generated with domain parameters taken from this list.  The exact
2760 format of this parameter depends on the actual algorithm.  It is
2761 currently only implemented for DSA using this format:
2762
2763 @example
2764 (genkey
2765   (dsa
2766     (domain
2767       (p @var{p-mpi})
2768       (q @var{q-mpi})
2769       (g @var{q-mpi}))))
2770 @end example
2771
2772 @code{nbits} and @code{qbits} may not be specified because they are
2773 derived from the domain parameters.
2774
2775 @item derive-parms
2776 This is currently only implemented for RSA and DSA keys.  It is not
2777 allowed to use this together with a @code{domain} specification.  If
2778 given, it is used to derive the keys using the given parameters.
2779
2780 If given for an RSA key the X9.31 key generation algorithm is used
2781 even if libgcrypt is not in FIPS mode.  If given for a DSA key, the
2782 FIPS 186 algorithm is used even if libgcrypt is not in FIPS mode.
2783
2784 @example
2785 (genkey
2786   (rsa
2787     (nbits 4:1024)
2788     (rsa-use-e 1:3)
2789     (derive-parms
2790       (Xp1 #1A1916DDB29B4EB7EB6732E128#)
2791       (Xp2 #192E8AAC41C576C822D93EA433#)
2792       (Xp  #D8CD81F035EC57EFE822955149D3BFF70C53520D
2793             769D6D76646C7A792E16EBD89FE6FC5B605A6493
2794             39DFC925A86A4C6D150B71B9EEA02D68885F5009
2795             B98BD984#)
2796       (Xq1 #1A5CF72EE770DE50CB09ACCEA9#)
2797       (Xq2 #134E4CAA16D2350A21D775C404#)
2798       (Xq  #CC1092495D867E64065DEE3E7955F2EBC7D47A2D
2799             7C9953388F97DDDC3E1CA19C35CA659EDC2FC325
2800             6D29C2627479C086A699A49C4C9CEE7EF7BD1B34
2801             321DE34A#))))
2802 @end example
2803
2804 @example
2805 (genkey
2806   (dsa
2807     (nbits 4:1024)
2808     (derive-parms
2809       (seed @var{seed-mpi}))))
2810 @end example
2811
2812
2813 @item use-x931
2814 @cindex X9.31
2815 Force the use of the ANSI X9.31 key generation algorithm instead of
2816 the default algorithm. This flag is only meaningful for RSA and
2817 usually not required.  Note that this algorithm is implicitly used if
2818 either @code{derive-parms} is given or Libgcrypt is in FIPS mode.
2819
2820 @item use-fips186
2821 @cindex FIPS 186
2822 Force the use of the FIPS 186 key generation algorithm instead of the
2823 default algorithm.  This flag is only meaningful for DSA and usually
2824 not required.  Note that this algorithm is implicitly used if either
2825 @code{derive-parms} is given or Libgcrypt is in FIPS mode.  As of now
2826 FIPS 186-2 is implemented; after the approval of FIPS 186-3 the code
2827 will be changed to implement 186-3.
2828
2829
2830 @item use-fips186-2
2831 Force the use of the FIPS 186-2 key generation algorithm instead of
2832 the default algorithm.  This algorithm is slighlty different from
2833 FIPS 186-3 and allows only 1024 bit keys.  This flag is only meaningful
2834 for DSA and only required for FIPS testing backward compatibility.
2835
2836
2837 @end table
2838 @c end table of parameters
2839
2840 @noindent
2841 The key pair is returned in a format depending on the algorithm.  Both
2842 private and public keys are returned in one container and may be
2843 accompanied by some miscellaneous information.
2844
2845 @noindent
2846 As an example, here is what the Elgamal key generation returns:
2847
2848 @example
2849 (key-data
2850   (public-key
2851     (elg
2852       (p @var{p-mpi})
2853       (g @var{g-mpi})
2854       (y @var{y-mpi})))
2855   (private-key
2856     (elg
2857       (p @var{p-mpi})
2858       (g @var{g-mpi})
2859       (y @var{y-mpi})
2860       (x @var{x-mpi})))
2861   (misc-key-info
2862     (pm1-factors @var{n1 n2 ... nn}))
2863 @end example
2864
2865 @noindent
2866 As you can see, some of the information is duplicated, but this
2867 provides an easy way to extract either the public or the private key.
2868 Note that the order of the elements is not defined, e.g. the private
2869 key may be stored before the public key. @var{n1 n2 ... nn} is a list
2870 of prime numbers used to composite @var{p-mpi}; this is in general not
2871 a very useful information and only available if the key generation
2872 algorithm provides them.
2873 @end deftypefun
2874 @c end gcry_pk_genkey
2875
2876 @node AC Interface
2877 @section Alternative Public Key Interface
2878
2879 This section documents the alternative interface to asymmetric
2880 cryptography (ac) that is not based on S-expressions, but on native C
2881 data structures.  As opposed to the pk interface described in the
2882 former chapter, this one follows an open/use/close paradigm like other
2883 building blocks of the library.
2884
2885 @strong{This interface has a few known problems; most noteworthy an
2886 inherent tendency to leak memory.  It might not be available in
2887 forthcoming versions of Libgcrypt.}
2888
2889
2890 @menu
2891 * Available asymmetric algorithms::  List of algorithms supported by the library.
2892 * Working with sets of data::   How to work with sets of data.
2893 * Working with IO objects::     How to work with IO objects.
2894 * Working with handles::        How to use handles.
2895 * Working with keys::           How to work with keys.
2896 * Using cryptographic functions::  How to perform cryptographic operations.
2897 * Handle-independent functions::  General functions independent of handles.
2898 @end menu
2899
2900 @node Available asymmetric algorithms
2901 @subsection Available asymmetric algorithms
2902
2903 Libgcrypt supports the RSA (Rivest-Shamir-Adleman)
2904 algorithms as well as DSA (Digital Signature Algorithm) and Elgamal.
2905 The versatile interface allows to add more algorithms in the future.
2906
2907 @deftp {Data type} gcry_ac_id_t
2908
2909 The following constants are defined for this type:
2910
2911 @table @code
2912 @item GCRY_AC_RSA
2913 Rivest-Shamir-Adleman
2914 @item GCRY_AC_DSA
2915 Digital Signature Algorithm
2916 @item GCRY_AC_ELG
2917 Elgamal
2918 @item GCRY_AC_ELG_E
2919 Elgamal, encryption only.
2920 @end table
2921 @end deftp
2922
2923 @node Working with sets of data
2924 @subsection Working with sets of data
2925
2926 In the context of this interface the term `data set' refers to a list
2927 of `named MPI values' that is used by functions performing
2928 cryptographic operations; a named MPI value is a an MPI value,
2929 associated with a label.
2930
2931 Such data sets are used for representing keys, since keys simply
2932 consist of a variable amount of numbers.  Furthermore some functions
2933 return data sets to the caller that are to be provided to other
2934 functions.
2935
2936 This section documents the data types, symbols and functions that are
2937 relevant for working with data sets.
2938
2939 @deftp {Data type} gcry_ac_data_t
2940 A single data set.
2941 @end deftp
2942
2943 The following flags are supported:
2944
2945 @table @code
2946 @item GCRY_AC_FLAG_DEALLOC
2947 Used for storing data in a data set.  If given, the data will be
2948 released by the library.  Note that whenever one of the ac functions
2949 is about to release objects because of this flag, the objects are
2950 expected to be stored in memory allocated through the Libgcrypt memory
2951 management.  In other words: gcry_free() is used instead of free().
2952
2953 @item GCRY_AC_FLAG_COPY
2954 Used for storing/retrieving data in/from a data set.  If given, the
2955 library will create copies of the provided/contained data, which will
2956 then be given to the user/associated with the data set.
2957 @end table
2958
2959 @deftypefun gcry_error_t gcry_ac_data_new (gcry_ac_data_t *@var{data})
2960 Creates a new, empty data set and stores it in @var{data}.
2961 @end deftypefun
2962
2963 @deftypefun void gcry_ac_data_destroy (gcry_ac_data_t @var{data})
2964 Destroys the data set @var{data}.
2965 @end deftypefun
2966
2967 @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})
2968 Add the value @var{mpi} to @var{data} with the label @var{name}.  If
2969 @var{flags} contains GCRY_AC_FLAG_COPY, the data set will contain
2970 copies of @var{name} and @var{mpi}.  If @var{flags} contains
2971 GCRY_AC_FLAG_DEALLOC or GCRY_AC_FLAG_COPY, the values
2972 contained in the data set will be deallocated when they are to be
2973 removed from the data set.
2974 @end deftypefun
2975
2976 @deftypefun gcry_error_t gcry_ac_data_copy (gcry_ac_data_t *@var{data_cp}, gcry_ac_data_t @var{data})
2977 Create a copy of the data set @var{data} and store it in
2978 @var{data_cp}.  FIXME: exact semantics undefined.
2979 @end deftypefun
2980
2981 @deftypefun {unsigned int} gcry_ac_data_length (gcry_ac_data_t @var{data})
2982 Returns the number of named MPI values inside of the data set
2983 @var{data}.
2984 @end deftypefun
2985
2986 @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})
2987 Store the value labelled with @var{name} found in @var{data} in
2988 @var{mpi}.  If @var{flags} contains GCRY_AC_FLAG_COPY, store a copy of
2989 the @var{mpi} value contained in the data set.  @var{mpi} may be NULL
2990 (this might be useful for checking the existence of an MPI with
2991 extracting it).
2992 @end deftypefun
2993
2994 @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})
2995 Stores in @var{name} and @var{mpi} the named @var{mpi} value contained
2996 in the data set @var{data} with the index @var{idx}.  If @var{flags}
2997 contains GCRY_AC_FLAG_COPY, store copies of the values contained in
2998 the data set. @var{name} or @var{mpi} may be NULL.
2999 @end deftypefun
3000
3001 @deftypefun void gcry_ac_data_clear (gcry_ac_data_t @var{data})
3002 Destroys any values contained in the data set @var{data}.
3003 @end deftypefun
3004
3005 @deftypefun gcry_error_t gcry_ac_data_to_sexp (gcry_ac_data_t @var{data}, gcry_sexp_t *@var{sexp}, const char **@var{identifiers})
3006 This function converts the data set @var{data} into a newly created
3007 S-Expression, which is to be stored in @var{sexp}; @var{identifiers}
3008 is a NULL terminated list of C strings, which specifies the structure
3009 of the S-Expression.
3010
3011 Example:
3012
3013 If @var{identifiers} is a list of pointers to the strings ``foo'' and
3014 ``bar'' and if @var{data} is a data set containing the values ``val1 =
3015 0x01'' and ``val2 = 0x02'', then the resulting S-Expression will look
3016 like this: (foo (bar ((val1 0x01) (val2 0x02))).
3017 @end deftypefun
3018
3019 @deftypefun gcry_error gcry_ac_data_from_sexp (gcry_ac_data_t *@var{data}, gcry_sexp_t @var{sexp}, const char **@var{identifiers})
3020 This function converts the S-Expression @var{sexp} into a newly
3021 created data set, which is to be stored in @var{data};
3022 @var{identifiers} is a NULL terminated list of C strings, which
3023 specifies the structure of the S-Expression.  If the list of
3024 identifiers does not match the structure of the S-Expression, the
3025 function fails.
3026 @end deftypefun
3027
3028 @node Working with IO objects
3029 @subsection Working with IO objects
3030
3031 Note: IO objects are currently only used in the context of message
3032 encoding/decoding and encryption/signature schemes.
3033
3034 @deftp {Data type} {gcry_ac_io_t}
3035 @code{gcry_ac_io_t} is the type to be used for IO objects.
3036 @end deftp
3037
3038 IO objects provide an uniform IO layer on top of different underlying
3039 IO mechanisms; either they can be used for providing data to the
3040 library (mode is GCRY_AC_IO_READABLE) or they can be used for
3041 retrieving data from the library (mode is GCRY_AC_IO_WRITABLE).
3042
3043 IO object need to be initialized by calling on of the following
3044 functions:
3045
3046 @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}, ...);
3047 Initialize @var{ac_io} according to @var{mode}, @var{type} and the
3048 variable list of arguments.  The list of variable arguments to specify
3049 depends on the given @var{type}.
3050 @end deftypefun
3051
3052 @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});
3053 Initialize @var{ac_io} according to @var{mode}, @var{type} and the
3054 variable list of arguments @var{ap}.  The list of variable arguments
3055 to specify depends on the given @var{type}.
3056 @end deftypefun
3057
3058 The following types of IO objects exist:
3059
3060 @table @code
3061 @item GCRY_AC_IO_STRING
3062 In case of GCRY_AC_IO_READABLE the IO object will provide data from a
3063 memory string.  Arguments to specify at initialization time:
3064 @table @code
3065 @item unsigned char *
3066 Pointer to the beginning of the memory string
3067 @item size_t
3068 Size of the memory string
3069 @end table
3070 In case of GCRY_AC_IO_WRITABLE the object will store retrieved data in
3071 a newly allocated memory string.  Arguments to specify at
3072 initialization time:
3073 @table @code
3074 @item unsigned char **
3075 Pointer to address, at which the pointer to the newly created memory
3076 string is to be stored
3077 @item size_t *
3078 Pointer to address, at which the size of the newly created memory
3079 string is to be stored
3080 @end table
3081
3082 @item GCRY_AC_IO_CALLBACK
3083 In case of GCRY_AC_IO_READABLE the object will forward read requests
3084 to a provided callback function.  Arguments to specify at
3085 initialization time:
3086 @table @code
3087 @item gcry_ac_data_read_cb_t
3088 Callback function to use
3089 @item void *
3090 Opaque argument to provide to the callback function
3091 @end table
3092 In case of GCRY_AC_IO_WRITABLE the object will forward write requests
3093 to a provided callback function.  Arguments to specify at
3094 initialization time:
3095 @table @code
3096 @item gcry_ac_data_write_cb_t
3097 Callback function to use
3098 @item void *
3099 Opaque argument to provide to the callback function
3100 @end table
3101 @end table
3102
3103 @node Working with handles
3104 @subsection Working with handles
3105
3106 In order to use an algorithm, an according handle must be created.
3107 This is done using the following function:
3108
3109 @deftypefun gcry_error_t gcry_ac_open (gcry_ac_handle_t *@var{handle}, int @var{algorithm}, int @var{flags})
3110
3111 Creates a new handle for the algorithm @var{algorithm} and stores it
3112 in @var{handle}.  @var{flags} is not used currently.
3113
3114 @var{algorithm} must be a valid algorithm ID, see @xref{Available
3115 asymmetric algorithms}, for a list of supported algorithms and the
3116 according constants.  Besides using the listed constants directly, the
3117 functions @code{gcry_pk_name_to_id} may be used to convert the textual
3118 name of an algorithm into the according numeric ID.
3119 @end deftypefun
3120
3121 @deftypefun void gcry_ac_close (gcry_ac_handle_t @var{handle})
3122 Destroys the handle @var{handle}.
3123 @end deftypefun
3124
3125 @node Working with keys
3126 @subsection Working with keys
3127
3128 @deftp {Data type} gcry_ac_key_type_t
3129 Defined constants:
3130
3131 @table @code
3132 @item GCRY_AC_KEY_SECRET
3133 Specifies a secret key.
3134 @item GCRY_AC_KEY_PUBLIC
3135 Specifies a public key.
3136 @end table
3137 @end deftp
3138
3139 @deftp {Data type} gcry_ac_key_t
3140 This type represents a single `key', either a secret one or a public
3141 one.
3142 @end deftp
3143
3144 @deftp {Data type} gcry_ac_key_pair_t
3145 This type represents a `key pair' containing a secret and a public key.
3146 @end deftp
3147
3148 Key data structures can be created in two different ways; a new key
3149 pair can be generated, resulting in ready-to-use key.  Alternatively a
3150 key can be initialized from a given data set.
3151
3152 @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})
3153 Creates a new key of type @var{type}, consisting of the MPI values
3154 contained in the data set @var{data} and stores it in @var{key}.
3155 @end deftypefun
3156
3157 @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})
3158
3159 Generates a new key pair via the handle @var{handle} of @var{NBITS}
3160 bits and stores it in @var{key_pair}.
3161
3162 In case non-standard settings are wanted, a pointer to a structure of
3163 type @code{gcry_ac_key_spec_<algorithm>_t}, matching the selected
3164 algorithm, can be given as @var{key_spec}.  @var{misc_data} is not
3165 used yet.  Such a structure does only exist for RSA.  A description
3166 of the members of the supported structures follows.
3167
3168 @table @code
3169 @item gcry_ac_key_spec_rsa_t
3170 @table @code
3171 @item gcry_mpi_t e
3172 Generate the key pair using a special @code{e}.  The value of @code{e}
3173 has the following meanings:
3174 @table @code
3175 @item = 0
3176 Let Libgcrypt decide what exponent should be used.
3177 @item = 1
3178 Request the use of a ``secure'' exponent; this is required by some
3179 specification to be 65537.
3180 @item > 2
3181 Try starting at this value until a working exponent is found.  Note
3182 that the current implementation leaks some information about the
3183 private key because the incrementation used is not randomized.  Thus,
3184 this function will be changed in the future to return a random
3185 exponent of the given size.
3186 @end table
3187 @end table
3188 @end table
3189
3190 Example code:
3191 @example
3192 @{
3193   gcry_ac_key_pair_t key_pair;
3194   gcry_ac_key_spec_rsa_t rsa_spec;
3195
3196   rsa_spec.e = gcry_mpi_new (0);
3197   gcry_mpi_set_ui (rsa_spec.e, 1);
3198
3199   err = gcry_ac_open  (&handle, GCRY_AC_RSA, 0);
3200   assert (! err);
3201
3202   err = gcry_ac_key_pair_generate (handle, 1024, &rsa_spec,
3203                                    &key_pair, NULL);
3204   assert (! err);
3205 @}
3206 @end example
3207 @end deftypefun
3208
3209
3210 @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})
3211 Returns the key of type @var{which} out of the key pair
3212 @var{key_pair}.
3213 @end deftypefun
3214
3215 @deftypefun void gcry_ac_key_destroy (gcry_ac_key_t @var{key})
3216 Destroys the key @var{key}.
3217 @end deftypefun
3218
3219 @deftypefun void gcry_ac_key_pair_destroy (gcry_ac_key_pair_t @var{key_pair})
3220 Destroys the key pair @var{key_pair}.
3221 @end deftypefun
3222
3223 @deftypefun gcry_ac_data_t gcry_ac_key_data_get (gcry_ac_key_t @var{key})
3224 Returns the data set contained in the key @var{key}.
3225 @end deftypefun
3226
3227 @deftypefun gcry_error_t gcry_ac_key_test (gcry_ac_handle_t @var{handle}, gcry_ac_key_t @var{key})
3228 Verifies that the private key @var{key} is sane via @var{handle}.
3229 @end deftypefun
3230
3231 @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})
3232 Stores the number of bits of the key @var{key} in @var{nbits} via @var{handle}.
3233 @end deftypefun
3234
3235 @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})
3236 Writes the 20 byte long key grip of the key @var{key} to
3237 @var{key_grip} via @var{handle}.
3238 @end deftypefun
3239
3240 @node Using cryptographic functions
3241 @subsection Using cryptographic functions
3242
3243 The following flags might be relevant:
3244
3245 @table @code
3246 @item GCRY_AC_FLAG_NO_BLINDING
3247 Disable any blinding, which might be supported by the chosen
3248 algorithm; blinding is the default.
3249 @end table
3250
3251 There exist two kinds of cryptographic functions available through the
3252 ac interface: primitives, and high-level functions.
3253
3254 Primitives deal with MPIs (data sets) directly; what they provide is
3255 direct access to the cryptographic operations provided by an algorithm
3256 implementation.
3257
3258 High-level functions deal with octet strings, according to a specified
3259 ``scheme''.  Schemes make use of ``encoding methods'', which are
3260 responsible for converting the provided octet strings into MPIs, which
3261 are then forwared to the cryptographic primitives.  Since schemes are
3262 to be used for a special purpose in order to achieve a particular
3263 security goal, there exist ``encryption schemes'' and ``signature
3264 schemes''.  Encoding methods can be used seperately or implicitly
3265 through schemes.
3266
3267 What follows is a description of the cryptographic primitives.
3268
3269 @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})
3270 Encrypts the plain text MPI value @var{data_plain} with the key public
3271 @var{key} under the control of the flags @var{flags} and stores the
3272 resulting data set into @var{data_encrypted}.
3273 @end deftypefun
3274
3275 @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})
3276 Decrypts the encrypted data contained in the data set
3277 @var{data_encrypted} with the secret key KEY under the control of the
3278 flags @var{flags} and stores the resulting plain text MPI value in
3279 @var{DATA_PLAIN}.
3280 @end deftypefun
3281
3282 @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})
3283 Signs the data contained in @var{data} with the secret key @var{key}
3284 and stores the resulting signature in the data set
3285 @var{data_signature}.
3286 @end deftypefun
3287
3288 @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})
3289 Verifies that the signature contained in the data set
3290 @var{data_signature} is indeed the result of signing the data
3291 contained in @var{data} with the secret key belonging to the public
3292 key @var{key}.
3293 @end deftypefun
3294
3295 What follows is a description of the high-level functions.
3296
3297 The type ``gcry_ac_em_t'' is used for specifying encoding methods; the
3298 following methods are supported:
3299
3300 @table @code
3301 @item GCRY_AC_EME_PKCS_V1_5
3302 PKCS-V1_5 Encoding Method for Encryption.  Options must be provided
3303 through a pointer to a correctly initialized object of type
3304 gcry_ac_eme_pkcs_v1_5_t.
3305
3306 @item GCRY_AC_EMSA_PKCS_V1_5
3307 PKCS-V1_5 Encoding Method for Signatures with Appendix.  Options must
3308 be provided through a pointer to a correctly initialized object of
3309 type gcry_ac_emsa_pkcs_v1_5_t.
3310 @end table
3311
3312 Option structure types:
3313
3314 @table @code
3315 @item gcry_ac_eme_pkcs_v1_5_t
3316 @table @code
3317 @item gcry_ac_key_t key
3318 @item gcry_ac_handle_t handle
3319 @end table
3320 @item gcry_ac_emsa_pkcs_v1_5_t
3321 @table @code
3322 @item gcry_md_algo_t md
3323 @item size_t em_n
3324 @end table
3325 @end table
3326
3327 Encoding methods can be used directly through the following functions:
3328
3329 @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})
3330 Encodes the message contained in @var{m} of size @var{m_n} according
3331 to @var{method}, @var{flags} and @var{options}.  The newly created
3332 encoded message is stored in @var{em} and @var{em_n}.
3333 @end deftypefun
3334
3335 @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})
3336 Decodes the message contained in @var{em} of size @var{em_n} according
3337 to @var{method}, @var{flags} and @var{options}.  The newly created
3338 decoded message is stored in @var{m} and @var{m_n}.
3339 @end deftypefun
3340
3341 The type ``gcry_ac_scheme_t'' is used for specifying schemes; the
3342 following schemes are supported:
3343
3344 @table @code
3345 @item GCRY_AC_ES_PKCS_V1_5
3346 PKCS-V1_5 Encryption Scheme.  No options can be provided.
3347 @item GCRY_AC_SSA_PKCS_V1_5
3348 PKCS-V1_5 Signature Scheme (with Appendix).  Options can be provided
3349 through a pointer to a correctly initialized object of type
3350 gcry_ac_ssa_pkcs_v1_5_t.
3351 @end table
3352
3353 Option structure types:
3354
3355 @table @code
3356 @item gcry_ac_ssa_pkcs_v1_5_t
3357 @table @code
3358 @item gcry_md_algo_t md
3359 @end table
3360 @end table
3361
3362 The functions implementing schemes:
3363
3364 @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})
3365 Encrypts the plain text readable from @var{io_message} through
3366 @var{handle} with the public key @var{key} according to @var{scheme},
3367 @var{flags} and @var{opts}.  If @var{opts} is not NULL, it has to be a
3368 pointer to a structure specific to the chosen scheme (gcry_ac_es_*_t).
3369 The encrypted message is written to @var{io_cipher}.
3370 @end deftypefun
3371
3372 @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})
3373 Decrypts the cipher text readable from @var{io_cipher} through
3374 @var{handle} with the secret key @var{key} according to @var{scheme},
3375 @var{flags} and @var{opts}.  If @var{opts} is not NULL, it has to be a
3376 pointer to a structure specific to the chosen scheme (gcry_ac_es_*_t).
3377 The decrypted message is written to @var{io_message}.
3378 @end deftypefun
3379
3380 @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})
3381 Signs the message readable from @var{io_message} through @var{handle}
3382 with the secret key @var{key} according to @var{scheme}, @var{flags}
3383 and @var{opts}.  If @var{opts} is not NULL, it has to be a pointer to
3384 a structure specific to the chosen scheme (gcry_ac_ssa_*_t).  The
3385 signature is written to @var{io_signature}.
3386 @end deftypefun
3387
3388 @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})
3389 Verifies through @var{handle} that the signature readable from
3390 @var{io_signature} is indeed the result of signing the message
3391 readable from @var{io_message} with the secret key belonging to the
3392 public key @var{key} according to @var{scheme} and @var{opts}.  If
3393 @var{opts} is not NULL, it has to be an anonymous structure
3394 (gcry_ac_ssa_*_t) specific to the chosen scheme.
3395 @end deftypefun
3396
3397 @node Handle-independent functions
3398 @subsection Handle-independent functions
3399
3400 These two functions are deprecated; do not use them for new code.
3401
3402 @deftypefun gcry_error_t gcry_ac_id_to_name (gcry_ac_id_t @var{algorithm}, const char **@var{name})
3403 Stores the textual representation of the algorithm whose id is given
3404 in @var{algorithm} in @var{name}.  Deprecated; use @code{gcry_pk_algo_name}.
3405 @end deftypefun
3406
3407 @deftypefun gcry_error_t gcry_ac_name_to_id (const char *@var{name}, gcry_ac_id_t *@var{algorithm})
3408 Stores the numeric ID of the algorithm whose textual representation is
3409 contained in @var{name} in @var{algorithm}. Deprecated; use
3410 @code{gcry_pk_map_name}.
3411 @end deftypefun
3412
3413 @c **********************************************************
3414 @c *******************  Hash Functions  *********************
3415 @c **********************************************************
3416 @node Hashing
3417 @chapter Hashing
3418
3419 Libgcrypt provides an easy and consistent to use interface for hashing.
3420 Hashing is buffered and several hash algorithms can be updated at once.
3421 It is possible to compute a MAC using the same routines.  The
3422 programming model follows an open/process/close paradigm and is in that
3423 similar to other building blocks provided by Libgcrypt.
3424
3425 For convenience reasons, a few cyclic redundancy check value operations
3426 are also supported.
3427
3428 @menu
3429 * Available hash algorithms::   List of hash algorithms supported by the library.
3430 * Hash algorithm modules::      How to work with hash algorithm modules.
3431 * Working with hash algorithms::  List of functions related to hashing.
3432 @end menu
3433
3434 @node Available hash algorithms
3435 @section Available hash algorithms
3436
3437 @c begin table of hash algorithms
3438 @cindex SHA-1
3439 @cindex SHA-224, SHA-256, SHA-384, SHA-512
3440 @cindex RIPE-MD-160
3441 @cindex MD2, MD4, MD5
3442 @cindex TIGER, TIGER1, TIGER2
3443 @cindex HAVAL
3444 @cindex Whirlpool
3445 @cindex CRC32
3446 @table @code
3447 @item GCRY_MD_NONE
3448 This is not a real algorithm but used by some functions as an error
3449 return value.  This constant is guaranteed to have the value @code{0}.
3450
3451 @item GCRY_MD_SHA1
3452 This is the SHA-1 algorithm which yields a message digest of 20 bytes.
3453 Note that SHA-1 begins to show some weaknesses and it is suggested to
3454 fade out its use if strong cryptographic properties are required.
3455
3456 @item GCRY_MD_RMD160
3457 This is the 160 bit version of the RIPE message digest (RIPE-MD-160).
3458 Like SHA-1 it also yields a digest of 20 bytes.  This algorithm share a
3459 lot of design properties with SHA-1 and thus it is advisable not to use
3460 it for new protocols.
3461
3462 @item GCRY_MD_MD5
3463 This is the well known MD5 algorithm, which yields a message digest of
3464 16 bytes.  Note that the MD5 algorithm has severe weaknesses, for
3465 example it is easy to compute two messages yielding the same hash
3466 (collision attack).  The use of this algorithm is only justified for
3467 non-cryptographic application.
3468
3469
3470 @item GCRY_MD_MD4
3471 This is the MD4 algorithm, which yields a message digest of 16 bytes.
3472 This algorithms ha severe weaknesses and should not be used.
3473
3474 @item GCRY_MD_MD2
3475 This is an reserved identifier for MD-2; there is no implementation yet.
3476 This algorithm has severe weaknesses and should not be used.
3477
3478 @item GCRY_MD_TIGER
3479 This is the TIGER/192 algorithm which yields a message digest of 24
3480 bytes.  Actually this is a variant of TIGER with a different output
3481 print order as used by GnuPG up to version 1.3.2.
3482
3483 @item GCRY_MD_TIGER1
3484 This is the TIGER variant as used by the NESSIE project.  It uses the
3485 most commonly used output print order.
3486
3487 @item GCRY_MD_TIGER2
3488 This is another variant of TIGER with a different padding scheme.
3489
3490
3491 @item GCRY_MD_HAVAL
3492 This is an reserved value for the HAVAL algorithm with 5 passes and 160
3493 bit. It yields a message digest of 20 bytes.  Note that there is no
3494 implementation yet available.
3495
3496 @item GCRY_MD_SHA224
3497 This is the SHA-224 algorithm which yields a message digest of 28 bytes.
3498 See Change Notice 1 for FIPS 180-2 for the specification.
3499
3500 @item GCRY_MD_SHA256
3501 This is the SHA-256 algorithm which yields a message digest of 32 bytes.
3502 See FIPS 180-2 for the specification.
3503
3504 @item GCRY_MD_SHA384
3505 This is the SHA-384 algorithm which yields a message digest of 48 bytes.
3506 See FIPS 180-2 for the specification.
3507
3508 @item GCRY_MD_SHA512
3509 This is the SHA-384 algorithm which yields a message digest of 64 bytes.
3510 See FIPS 180-2 for the specification.
3511
3512 @item GCRY_MD_CRC32
3513 This is the ISO 3309 and ITU-T V.42 cyclic redundancy check.  It yields
3514 an output of 4 bytes.  Note that this is not a hash algorithm in the
3515 cryptographic sense.
3516
3517 @item GCRY_MD_CRC32_RFC1510
3518 This is the above cyclic redundancy check function, as modified by RFC
3519 1510.  It yields an output of 4 bytes.  Note that this is not a hash
3520 algorithm in the cryptographic sense.
3521
3522 @item GCRY_MD_CRC24_RFC2440
3523 This is the OpenPGP cyclic redundancy check function.  It yields an
3524 output of 3 bytes.  Note that this is not a hash algorithm in the
3525 cryptographic sense.
3526
3527 @item GCRY_MD_WHIRLPOOL
3528 This is the Whirlpool algorithm which yields a message digest of 64
3529 bytes.
3530
3531 @end table
3532 @c end table of hash algorithms
3533
3534 @node Hash algorithm modules
3535 @section Hash algorithm modules
3536
3537 Libgcrypt makes it possible to load additional `message
3538 digest modules'; these digests can be used just like the message digest
3539 algorithms that are built into the library directly.  For an
3540 introduction into extension modules, see @xref{Modules}.
3541
3542 @deftp {Data type} gcry_md_spec_t
3543 This is the `module specification structure' needed for registering
3544 message digest modules, which has to be filled in by the user before
3545 it can be used to register a module.  It contains the following
3546 members:
3547
3548 @table @code
3549 @item const char *name
3550 The primary name of this algorithm.
3551 @item unsigned char *asnoid
3552 Array of bytes that form the ASN OID.
3553 @item int asnlen
3554 Length of bytes in `asnoid'.
3555 @item gcry_md_oid_spec_t *oids
3556 A list of OIDs that are to be associated with the algorithm.  The
3557 list's last element must have it's `oid' member set to NULL.  See
3558 below for an explanation of this type.  See below for an explanation
3559 of this type.
3560 @item int mdlen
3561 Length of the message digest algorithm.  See below for an explanation
3562 of this type.
3563 @item gcry_md_init_t init
3564 The function responsible for initializing a handle.  See below for an
3565 explanation of this type.
3566 @item gcry_md_write_t write
3567 The function responsible for writing data into a message digest
3568 context.  See below for an explanation of this type.
3569 @item gcry_md_final_t final
3570 The function responsible for `finalizing' a message digest context.
3571 See below for an explanation of this type.
3572 @item gcry_md_read_t read
3573 The function responsible for reading out a message digest result.  See
3574 below for an explanation of this type.
3575 @item size_t contextsize
3576 The size of the algorithm-specific `context', that should be
3577 allocated for each handle.
3578 @end table
3579 @end deftp
3580
3581 @deftp {Data type} gcry_md_oid_spec_t
3582 This type is used for associating a user-provided algorithm
3583 implementation with certain OIDs.  It contains the following members:
3584
3585 @table @code
3586 @item const char *oidstring
3587 Textual representation of the OID.
3588 @end table
3589 @end deftp
3590
3591 @deftp {Data type} gcry_md_init_t
3592 Type for the `init' function, defined as: void (*gcry_md_init_t) (void
3593 *c)
3594 @end deftp
3595
3596 @deftp {Data type} gcry_md_write_t
3597 Type for the `write' function, defined as: void (*gcry_md_write_t)
3598 (void *c, unsigned char *buf, size_t nbytes)
3599 @end deftp
3600
3601 @deftp {Data type} gcry_md_final_t
3602 Type for the `final' function, defined as: void (*gcry_md_final_t)
3603 (void *c)
3604 @end deftp
3605
3606 @deftp {Data type} gcry_md_read_t
3607 Type for the `read' function, defined as: unsigned char
3608 *(*gcry_md_read_t) (void *c)
3609 @end deftp
3610
3611 @deftypefun gcry_error_t gcry_md_register (gcry_md_spec_t *@var{digest}, unsigned int *algorithm_id, gcry_module_t *@var{module})
3612
3613 Register a new digest module whose specification can be found in
3614 @var{digest}.  On success, a new algorithm ID is stored in
3615 @var{algorithm_id} and a pointer representing this module is stored
3616 in @var{module}.  Deprecated; the module register interface will be
3617 removed in a future version.
3618 @end deftypefun
3619
3620 @deftypefun void gcry_md_unregister (gcry_module_t @var{module})
3621 Unregister the digest identified by @var{module}, which must have been
3622 registered with gcry_md_register.
3623 @end deftypefun
3624
3625 @deftypefun gcry_error_t gcry_md_list (int *@var{list}, int *@var{list_length})
3626 Get a list consisting of the IDs of the loaded message digest modules.
3627 If @var{list} is zero, write the number of loaded message digest
3628 modules to @var{list_length} and return.  If @var{list} is non-zero,
3629 the first *@var{list_length} algorithm IDs are stored in @var{list},
3630 which must be of according size.  In case there are less message
3631 digests modules than *@var{list_length}, *@var{list_length} is updated
3632 to the correct number.
3633 @end deftypefun
3634
3635 @node Working with hash algorithms
3636 @section Working with hash algorithms
3637
3638 To use most of these function it is necessary to create a context;
3639 this is done using:
3640
3641 @deftypefun gcry_error_t gcry_md_open (gcry_md_hd_t *@var{hd}, int @var{algo}, unsigned int @var{flags})
3642
3643 Create a message digest object for algorithm @var{algo}.  @var{flags}
3644 may be given as an bitwise OR of constants described below.  @var{algo}
3645 may be given as @code{0} if the algorithms to use are later set using
3646 @code{gcry_md_enable}. @var{hd} is guaranteed to either receive a valid
3647 handle or NULL.
3648
3649 For a list of supported algorithms, see @xref{Available hash
3650 algorithms}.
3651
3652 The flags allowed for @var{mode} are:
3653
3654 @c begin table of hash flags
3655 @table @code
3656 @item GCRY_MD_FLAG_SECURE
3657 Allocate all buffers and the resulting digest in "secure memory".  Use
3658 this is the hashed data is highly confidential.
3659
3660 @item GCRY_MD_FLAG_HMAC
3661 @cindex HMAC
3662 Turn the algorithm into a HMAC message authentication algorithm.  This
3663 only works if just one algorithm is enabled for the handle.  Note that
3664 the function @code{gcry_md_setkey} must be used to set the MAC key.
3665 The size of the MAC is equal to the message digest of the underlying
3666 hash algorithm.  If you want CBC message authentication codes based on
3667 a cipher, see @xref{Working with cipher handles}.
3668
3669 @end table
3670 @c begin table of hash flags
3671
3672 You may use the function @code{gcry_md_is_enabled} to later check
3673 whether an algorithm has been enabled.
3674
3675 @end deftypefun
3676 @c end function gcry_md_open
3677
3678 If you want to calculate several hash algorithms at the same time, you
3679 have to use the following function right after the @code{gcry_md_open}:
3680
3681 @deftypefun gcry_error_t gcry_md_enable (gcry_md_hd_t @var{h}, int @var{algo})
3682
3683 Add the message digest algorithm @var{algo} to the digest object
3684 described by handle @var{h}.  Duplicated enabling of algorithms is