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