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