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