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