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