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