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