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