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