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