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