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