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