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