2004-05-07 Moritz Schulte <moritz@g10code.de>
[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 General Public License as published by the
8 @c Free Software Foundation; either version 2 of the License, or (at your
9 @c option) any later version. A copy of the license is included in the 
10 @c file 'gpl.texi'.
11 @c
12 @setfilename gcrypt.info
13 @settitle The `Libgcrypt' Reference Manual
14
15 @dircategory GNU Libraries
16 @direntry
17 * libgcrypt: (gcrypt) Cryptographic function library.
18 @end direntry
19
20 @include version.texi
21
22 @c Unify some of the indices.
23 @syncodeindex tp fn
24 @syncodeindex pg fn
25
26 @ifinfo
27 This file documents the `Libgcrypt' library.
28
29 This is Edition @value{EDITION}, last updated @value{UPDATED}, of
30 @cite{The `Libgcrypt' Reference Manual}, for Version
31 @value{VERSION}.
32
33 Copyright @copyright{} 2000, 2002, 2003 Free Software Foundation, Inc.
34
35 Permission is granted to copy, distribute and/or modify this document
36 under the terms of the GNU General Public License as published by the
37 Free Software Foundation; either version 2 of the License, or (at your
38 option) any later version. The text of the license can be found in the
39 section entitled ``Copying''.
40 @end ifinfo
41
42 @c @iftex
43 @c @shorttitlepage The `Libgcrypt' Reference Manual
44 @c @end iftex
45 @titlepage
46 @center @titlefont{The `Libgcrypt'}
47 @sp 1
48 @center @titlefont{Reference Manual}
49 @sp 6
50 @center Edition @value{EDITION}
51 @sp 1
52 @center last updated @value{UPDATED}
53 @sp 1
54 @center for version @value{VERSION}
55 @page
56 @vskip 0pt plus 1filll
57 Copyright @copyright{} 2000, 2002, 2003 Free Software Foundation, Inc.
58
59 Permission is granted to copy, distribute and/or modify this document
60 under the terms of the GNU General Public License as published by the
61 Free Software Foundation; either version 2 of the License, or (at your
62 option) any later version. The text of the license can be found in the
63 section entitled ``Copying''.
64 @end titlepage
65 @summarycontents
66 @contents
67 @page
68
69 @ifnottex
70 @node Top
71 @top Main Menu
72 This is Edition @value{EDITION}, last updated @value{UPDATED}, of
73 @cite{The `Libgcrypt' Reference Manual}, for Version
74 @value{VERSION} of the @acronym{Libgcrypt} library.
75
76 Copyright @copyright{} 2000, 2002, 2003 Free Software Foundation, Inc.
77
78 Permission is granted to copy, distribute and/or modify this document
79 under the terms of the GNU General Public License as published by the
80 Free Software Foundation; either version 2 of the License, or (at your
81 option) any later version. The text of the license can be found in the
82 section entitled ``Copying''.
83
84 @end ifnottex
85
86 @menu
87 * Introduction::                 What is @acronym{Libgcrypt}.
88 * Preparation::                  What you should do before using the library.
89 * Generalities::                 General library functions and data types.
90 * Handler Functions::            Working with handler functions.
91 * Symmetric cryptography::       How to use symmetric crytography.
92 * Hashing::                      How to use hashing.
93 * Public Key cryptography (I)::  How to use public key cryptography.
94 * Public Key cryptography (II):: How to use public key cryptography, alternatively.
95 * Random Numbers::               How to work with random numbers.
96 * S-expressions::                How to manage S-expressions.
97 * MPI library::                  How to work with multi-precision-integers.
98 * Utilities::                    Utility functions.
99
100 Appendices
101
102 * Library Copying::             The GNU Lesser General Public License
103                                 says how you can copy and share `Libgcrypt'.
104 * Copying::                     The GNU General Public License says how you
105                                 can copy and share some parts of `Libgcrypt'.
106
107 Indices
108
109 * Concept Index::               Index of concepts and programs.
110 * Function and Data Index::     Index of functions, variables and data types.
111
112 @detailmenu
113  --- The Detailed Node Listing ---
114
115 Introduction
116 * Getting Started::             How to use this manual.
117 * Features::                    A glance at @acronym{Libgcrypt}'s features.
118 * Overview::                    Overview about the library.
119
120 Preparation
121 * Header::                              What header file you need to include.
122 * Building sources::                    How to build sources using the library.
123 * Building sources using Automake::     How to build sources with the help auf Automake.
124 * Initializing the library::            How to initialize the library.
125 * Multi Threading::                     How @acronym{Libgcrypt} can be used in a MT environment.
126
127 Generalities
128 * Controlling the library::     Controlling @acronym{Libgcrypt}'s behaviour.
129 * Modules::                     Description of extension modules.
130 * Error Handling::              Error codes and such.
131
132 Handler Functions
133 * Progress handler::            Using a progress handler function.
134 * Allocation handler::          Using special memory allocation functions.
135 * Error handler::               Using error handler functions.
136 * Logging handler::             Using a special logging function.
137
138 Symmetric cryptography
139 * Available ciphers::           List of ciphers supported by the library.
140 * Cipher modules::              How to work with cipher modules.
141 * Available cipher modes::      List of cipher modes supported by the library.
142 * Working with cipher handles:: How to perform operations related to cipher handles.
143 * General cipher functions::    General cipher functions independent of cipher handles.
144
145 Hashing
146 * Available hash algorithms::           List of hash algorithms supported by the library.
147 * Hash algorithm modules::              How to work with hash algorithm modules.
148 * Working with hash algorithms::        List of functions related to hashing.
149
150 Public Key cryptography (I)
151 * Used S-expressions::                    Introduction into the used S-expression.
152 * Available algorithms::                  Algorithms supported by the library.
153 * Public key modules::                    How to work with public key modules.
154 * Cryptographic Functions::               Functions for performing the cryptographic actions.
155 * General public-key related Functions::  General functions, not implementing any cryptography.
156
157 Public Key cryptography (II)
158 * Available asymmetric algorithms:: List of algorithms supported by the library.
159 * Working with sets of data::       How to work with sets of data.
160 * Working with handles::            How to use handles.
161 * Working with keys::               How to work with keys.
162 * Using cryptographic functions::   How to perform cryptographic operations.
163 * Handle-independent functions::    General functions independent of handles.
164
165 Random Numbers
166 * Quality of random numbers::   @acronym{Libgcrypt} uses different quality levels.
167 * Retrieving random numbers::   How to retrieve random numbers.
168
169 S-expressions
170 * Data types for S-expressions::   Data types related with S-expressions.
171 * Working with S-expressions::     How to work with S-expressions.
172
173 MPI library
174 * Data types::                  MPI related data types.
175 * Basic functions::             First steps with MPI numbers.
176 * MPI formats::                 External representation of MPIs.
177 * Calculations::                Performing MPI calculations.
178 * Comparisons::                 How to compare MPI values.
179 * Bit manipulations::           How to access single bits of MPI values.
180 * Misc::                        Miscellaneous MPI functions.
181
182 Utilities
183 * Memory allocation::           Functions related with memory allocation.
184
185 @end detailmenu
186
187 @end menu
188
189
190
191 @c **********************************************************
192 @c *******************  Introduction  ***********************
193 @c **********************************************************
194 @node Introduction
195 @chapter Introduction
196 `@acronym{Libgcrypt}' is a library providing cryptographic building blocks.
197
198 @menu
199 * Getting Started::             How to use this manual.
200 * Features::                    A glance at @acronym{Libgcrypt}'s features.
201 * Overview::                    Overview about the library.
202 @end menu
203
204 @node Getting Started
205 @section Getting Started
206
207 This manual documents the `@acronym{Libgcrypt}' library application programming
208 interface (API).  All functions and data types provided by the library
209 are explained.
210
211 The reader is assumed to possess basic knowledge about applied
212 cryptography.
213
214 This manual can be used in several ways.  If read from the beginning
215 to the end, it gives a good introduction into the library and how it
216 can be used in an application.  Forward references are included where
217 necessary.  Later on, the manual can be used as a reference manual to
218 get just the information needed about any particular interface of the
219 library.  Experienced programmers might want to start looking at the
220 examples at the end of the manual, and then only read up those parts
221 of the interface which are unclear.
222
223
224 @node Features
225 @section Features
226
227 @noindent
228 `Libgcrypt' might have a couple of advantages over other libraries doing
229 a similar job.
230
231 @table @asis
232 @item It's Free Software
233 Anybody can use, modify, and redistribute it under the terms of the GNU
234 Lesser General Public License (@pxref{Library Copying}).  Note, that
235 some parts (which are not needed on a GNU or GNU/Linux system) are
236 subject to the terms of the GNU General Public License
237 (@pxref{Copying}); please see the README file of the distribution for of
238 list of these parts.
239
240 @item It encapsulates the low level cryptography
241 `@acronym{Libgcrypt}' provides a high level interface to cryptographic building
242 blocks using an extendable and flexible API.
243
244 @end table
245
246
247 @node Overview
248 @section Overview
249
250 @noindent
251 The `@acronym{Libgcrypt}' library is fully thread-safe, where it makes
252 sense to be thread-safe.  An exception for thread-safety are some
253 cryptographic functions that modify a certain context stored in
254 handles.  If the user really intents to use such functions from
255 different threads on the same handle, he has to take care of the
256 serialisation of such functions himself.  If not described otherwise,
257 every function is thread-safe.
258
259 @acronym{Libgcrypt} depends on the library `libgpg-error', which
260 contains common error handling related code for GnuPG components.
261
262 @c **********************************************************
263 @c *******************  Preparation  ************************
264 @c **********************************************************
265 @node Preparation
266 @chapter Preparation
267
268 To use `@acronym{Libgcrypt}', you have to perform some changes to your
269 sources and the build system.  The necessary changes are small and
270 explained in the following sections.  At the end of this chapter, it
271 is described how the library is initialized, and how the requirements
272 of the library are verified.
273
274 @menu
275 * Header::                      What header file you need to include.
276 * Building sources::            How to build sources using the library.
277 * Building sources using Automake::  How to build sources with the help auf Automake.
278 * Initializing the library::    How to initialize the library.
279 * Multi Threading::             How @acronym{Libgcrypt} can be used in a MT environment.
280 @end menu
281
282
283 @node Header
284 @section Header
285
286 All interfaces (data types and functions) of the library are defined
287 in the header file `gcrypt.h'.  You must include this in all source
288 files using the library, either directly or through some other header
289 file, like this:
290
291 @example
292 #include <gcrypt.h>
293 @end example
294
295 The name space of `@acronym{Libgcrypt}' is @code{gcry_*} for function
296 and type names and @code{GCRY*} for other symbols.  In addition the
297 same name prefixes with one prepended underscore are reserved for
298 internal use and should never be used by an application.  Furthermore
299 `libgpg-error' defines functions prefixed with `gpg_' and preprocessor
300 symbols prefixed with `GPG_'.  Note that @acronym{Libgcrypt} uses
301 libgpg-error, which uses @code{gpg_err_*} as name space for function
302 and type names and @code{GPG_ERR_*} for other symbols, including all
303 the error codes.
304
305 @node Building sources
306 @section Building sources
307
308 If you want to compile a source file including the `gcrypt.h' header
309 file, you must make sure that the compiler can find it in the
310 directory hierarchy.  This is accomplished by adding the path to the
311 directory in which the header file is located to the compilers include
312 file search path (via the @option{-I} option).
313
314 However, the path to the include file is determined at the time the
315 source is configured.  To solve this problem, `@acronym{Libgcrypt}' ships with a small
316 helper program @command{libgcrypt-config} that knows the path to the
317 include file and other configuration options.  The options that need
318 to be added to the compiler invocation at compile time are output by
319 the @option{--cflags} option to @command{libgcrypt-config}.  The following
320 example shows how it can be used at the command line:
321
322 @example
323 gcc -c foo.c `libgcrypt-config --cflags`
324 @end example
325
326 Adding the output of @samp{libgcrypt-config --cflags} to the compilers
327 command line will ensure that the compiler can find the `@acronym{Libgcrypt}' header
328 file.
329
330 A similar problem occurs when linking the program with the library.
331 Again, the compiler has to find the library files.  For this to work,
332 the path to the library files has to be added to the library search path
333 (via the @option{-L} option).  For this, the option @option{--libs} to
334 @command{libgcrypt-config} can be used.  For convenience, this option
335 also outputs all other options that are required to link the program
336 with the `@acronym{Libgcrypt}' libraries (in particular, the @samp{-lgcrypt}
337 option).  The example shows how to link @file{foo.o} with the `@acronym{Libgcrypt}'
338 library to a program @command{foo}.
339
340 @example
341 gcc -o foo foo.o `libgcrypt-config --libs`
342 @end example
343
344 Of course you can also combine both examples to a single command by
345 specifying both options to @command{libgcrypt-config}:
346
347 @example
348 gcc -o foo foo.c `libgcrypt-config --cflags --libs`
349 @end example
350
351 @node Building sources using Automake
352 @section Building sources using Automake
353
354 It is much easier if you use GNU Automake instead of writing your own
355 Makefiles.  If you do that you do not have to worry about finding and
356 invoking the @command{libgcrypt-config} script at all.
357 @acronym{Libgcrypt} provides an extension to Automake that does all
358 the work for you.
359
360 @c A simple macro for optional variables.
361 @macro ovar{varname}
362 @r{[}@var{\varname\}@r{]}
363 @end macro
364 @defmac AM_PATH_LIBGCRYPT (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found})
365 Check whether @acronym{Libgcrypt} (at least version
366 @var{minimum-version}, if given) exists on the host system.  If it is
367 found, execute @var{action-if-found}, otherwise do
368 @var{action-if-not-found}, if given.
369
370 Additionally, the function defines @code{LIBGCRYPT_CFLAGS} to the
371 flags needed for compilation of the program to find the
372 @file{gcrypt.h} header file, and @code{LIBGCRYPT_LIBS} to the linker
373 flags needed to link the program to the @acronym{Libgcrypt} library.
374 @end defmac
375
376 You can use the defined Autoconf variables like this in your
377 @file{Makefile.am}:
378
379 @example
380 AM_CPPFLAGS = $(LIBGCRYPT_CFLAGS)
381 LDADD = $(LIBGCRYPT_LIBS)
382 @end example
383
384 @node Initializing the library
385 @section Initializing the library
386
387 It is often desirable to check that the version of `@acronym{Libgcrypt}' used is
388 indeed one which fits all requirements.  Even with binary compatibility
389 new features may have been introduced but due to problem with the
390 dynamic linker an old version is actually used.  So you may want to
391 check that the version is okay right after program startup.
392
393 @deftypefun const char *gcry_check_version (const char *@var{req_version})
394
395 The function @code{gcry_check_version} has three purposes.  It can be
396 used to retrieve the version number of the library.  In addition it
397 can verify that the version number is higher than a certain required
398 version number.
399
400 In either case, the function initializes some sub-systems, and for
401 this reason alone it must be invoked early in your program, before you
402 make use of the other functions of @acronym{Libgcrypt}.
403 @end deftypefun
404
405 @node Multi Threading
406 @section Multi Threading
407
408 As mentioned earlier, the `@acronym{Libgcrypt}' library is 
409 thread-safe if you adhere to the following requirements:
410
411 @itemize @bullet
412 @item
413 If your application is multi-threaded, you must set the thread support
414 callbacks with the @code{GCRYCTL_SET_THREAD_CBS} command
415 @strong{before} any other function in the library.
416
417 This is easy enough if you are indeed writing an application using
418 libgcrypt.  It is rather problematic if you are writing a library
419 instead.  Here are some tips what to do if you are writing a library:
420
421 If your library requires a certain thread package, just initialize
422 gcrypt to use this thread package.  If your library supports multiple
423 thread packages, but needs to be configured, you will have to
424 implement a way to determine which thread package the application
425 wants to use with your library anyway.  Then configure gcrypt to use
426 this thread package.
427
428 If your library is fully reentrant without any special support by a
429 thread package, then you are lucky indeed.  Unfortunately, this does
430 not relieve you from doing either of the two above, or use a third
431 option.  The third option is to let the application initialize gcrypt
432 for you.  Then you are not using gcrypt transparently, though.
433
434 As if this was not difficult enough, a conflict may arise if two
435 libraries try to initialize gcrypt independently of each others, and
436 both such libraries are then linked into the same application.  To
437 make it a bit simpler for you, this will probably work, but only if
438 both libraries have the same requirement for the thread package.  This
439 is currently only supported for the non-threaded case, GNU Pth and
440 pthread.  Support for more thread packages is easy to add, so contact
441 us if you require it.
442
443 @item
444 The function @code{gcry_check_version} must be called before any other
445 function in the library, except the @code{GCRYCTL_SET_THREAD_CBS}
446 command (called via the @code{gcry_control} function0, because it
447 initializes the thread support subsystem in @acronym{Libgcrypt}.  To
448 achieve this in multi-threaded programs, you must synchronize the
449 memory with respect to other threads that also want to use
450 @acronym{Libgcrypt}.  For this, it is sufficient to call
451 @code{gcry_check_version} before creating the other threads using
452 @acronym{Libgcrypt}@footnote{At least this is true for POSIX threads,
453 as @code{pthread_create} is a function that synchronizes memory with
454 respects to other threads.  There are many functions which have this
455 property, a complete list can be found in POSIX, IEEE Std 1003.1-2003,
456 Base Definitions, Issue 6, in the definition of the term ``Memory
457 Synchronization''.  For other thread packages, more relaxed or more
458 strict rules may apply.}.
459
460 @item
461 As with the function @code{gpg_strerror}, @code{gcry_strerror} is not
462 thread safe.  You have to use @code{gpg_strerror_r} instead.
463 @end itemize
464
465
466 @c **********************************************************
467 @c *******************  General  ****************************
468 @c **********************************************************
469 @node Generalities
470 @chapter Generalities
471
472 @menu
473 * Controlling the library::     Controlling @acronym{Libgcrypt}'s behaviour.
474 * Modules::                     Description of extension modules.
475 * Error Handling::              Error codes and such.
476 @end menu
477
478 @node Controlling the library
479 @section Controlling the library
480
481 @deftypefun gcry_error_t gcry_control (enum gcry_ctl_cmds @var{cmd}, ...)
482
483 This function can be used to influence the general behaviour of
484 @acronym{Libgcrypt} in several ways.  Depending on @var{cmd}, more
485 arguments can or have to be provided.
486
487 @end deftypefun
488
489 @node Modules
490 @section Modules
491
492 @acronym{Libgcrypt} supports the use of `extension modules', which
493 implement algorithms in addition to those already built into the
494 library directly.
495
496 @deftp {Data type} gcry_module_t
497 This data type represents a `module'.
498 @end deftp
499
500 Functions registering modules provided by the user take a `module
501 specification structure' as input and return a value of
502 @code{gcry_module_t} and an ID that is unique in the modules'
503 category.  This ID can be used to reference the newly registered
504 module.  After registering a module successfuly, the new functionality
505 should be able to be used through the normal functions provided by
506 @acronym{Libgcrypt} until it is unregistered again.
507
508 @c **********************************************************
509 @c *******************  Errors  ****************************
510 @c **********************************************************
511 @node Error Handling
512 @section Error Handling
513
514 Many functions in @acronym{Libgcrypt} can return an error if they
515 fail.  For this reason, the application should always catch the error
516 condition and take appropriate measures, for example by releasing the
517 resources and passing the error up to the caller, or by displaying a
518 descriptive message to the user and cancelling the operation.
519
520 Some error values do not indicate a system error or an error in the
521 operation, but the result of an operation that failed properly.  For
522 example, if you try to decrypt a tempered message, the decryption will
523 fail.  Another error value actually means that the end of a data
524 buffer or list has been reached.  The following descriptions explain
525 for many error codes what they mean usually.  Some error values have
526 specific meanings if returned by a certain functions.  Such cases are
527 described in the documentation of those functions.
528
529 @acronym{Libgcrypt} uses the @code{libgpg-error} library.  This allows
530 to share the error codes with other components of the GnuPG system,
531 and thus pass error values transparently from the crypto engine, or
532 some helper application of the crypto engine, to the user.  This way
533 no information is lost.  As a consequence, @acronym{Libgcrypt} does
534 not use its own identifiers for error codes, but uses those provided
535 by @code{libgpg-error}.  They usually start with @code{GPG_ERR_}.
536
537 However, @acronym{Libgcrypt} does provide aliases for the functions
538 defined in libgpg-error, which might be preferred for name space
539 consistency.
540
541
542 Most functions in @acronym{Libgcrypt} return an error code in the case
543 of failure.  For this reason, the application should always catch the
544 error condition and take appropriate measures, for example by
545 releasing the resources and passing the error up to the caller, or by
546 displaying a descriptive message to the user and canceling the
547 operation.
548
549 Some error values do not indicate a system error or an error in the
550 operation, but the result of an operation that failed properly.
551
552 GnuPG components, including libgcrypt, use an extra library named
553 libgpg-error to provide a common error handling scheme.  For more
554 information on libgpg-error, see the according manual.
555
556 @menu
557 * Error Values::                The error value and what it means.
558 * Error Sources::               A list of important error sources.
559 * Error Codes::                 A list of important error codes.
560 * Error Strings::               How to get a descriptive string from a value.
561 @end menu
562
563
564 @node Error Values
565 @subsection Error Values
566 @cindex error values
567 @cindex error codes
568 @cindex error sources
569
570 @deftp {Data type} {gcry_err_code_t}
571 The @code{gcry_err_code_t} type is an alias for the
572 @code{libgpg-error} type @code{gpg_err_code_t}.  The error code
573 indicates the type of an error, or the reason why an operation failed.
574
575 A list of important error codes can be found in the next section.
576 @end deftp
577
578 @deftp {Data type} {gcry_err_source_t}
579 The @code{gcry_err_source_t} type is an alias for the
580 @code{libgpg-error} type @code{gpg_err_source_t}.  The error source
581 has not a precisely defined meaning.  Sometimes it is the place where
582 the error happened, sometimes it is the place where an error was
583 encoded into an error value.  Usually the error source will give an
584 indication to where to look for the problem.  This is not always true,
585 but it is attempted to achieve this goal.
586
587 A list of important error sources can be found in the next section.
588 @end deftp
589
590 @deftp {Data type} {gcry_error_t}
591 The @code{gcry_error_t} type is an alias for the @code{libgpg-error}
592 type @code{gpg_error_t}.  An error value like this has always two
593 components, an error code and an error source.  Both together form the
594 error value.
595
596 Thus, the error value can not be directly compared against an error
597 code, but the accessor functions described below must be used.
598 However, it is guaranteed that only 0 is used to indicate success
599 (@code{GPG_ERR_NO_ERROR}), and that in this case all other parts of
600 the error value are set to 0, too.
601
602 Note that in @acronym{Libgcrypt}, the error source is used purely for
603 diagnostical purposes.  Only the error code should be checked to test
604 for a certain outcome of a function.  The manual only documents the
605 error code part of an error value.  The error source is left
606 unspecified and might be anything.
607 @end deftp
608
609 @deftypefun {gcry_err_code_t} gcry_err_code (@w{gcry_error_t @var{err}})
610 The static inline function @code{gcry_err_code} returns the
611 @code{gcry_err_code_t} component of the error value @var{err}.  This
612 function must be used to extract the error code from an error value in
613 order to compare it with the @code{GPG_ERR_*} error code macros.
614 @end deftypefun
615
616 @deftypefun {gcry_err_source_t} gcry_err_source (@w{gcry_error_t @var{err}})
617 The static inline function @code{gcry_err_source} returns the
618 @code{gcry_err_source_t} component of the error value @var{err}.  This
619 function must be used to extract the error source from an error value in
620 order to compare it with the @code{GPG_ERR_SOURCE_*} error source macros.
621 @end deftypefun
622
623 @deftypefun {gcry_error_t} gcry_err_make (@w{gcry_err_source_t @var{source}}, @w{gcry_err_code_t @var{code}})
624 The static inline function @code{gcry_err_make} returns the error
625 value consisting of the error source @var{source} and the error code
626 @var{code}.
627
628 This function can be used in callback functions to construct an error
629 value to return it to the library.
630 @end deftypefun
631
632 @deftypefun {gcry_error_t} gcry_error (@w{gcry_err_code_t @var{code}})
633 The static inline function @code{gcry_error} returns the error value
634 consisting of the default error source and the error code @var{code}.
635
636 For @acronym{GCRY} applications, the default error source is
637 @code{GPG_ERR_SOURCE_USER_1}.  You can define
638 @code{GCRY_ERR_SOURCE_DEFAULT} before including @file{gcrypt.h} to
639 change this default.
640
641 This function can be used in callback functions to construct an error
642 value to return it to the library.
643 @end deftypefun
644
645 The @code{libgpg-error} library provides error codes for all system
646 error numbers it knows about.  If @var{err} is an unknown error
647 number, the error code @code{GPG_ERR_UNKNOWN_ERRNO} is used.  The
648 following functions can be used to construct error values from system
649 errnor numbers.
650
651 @deftypefun {gcry_error_t} gcry_err_make_from_errno (@w{gcry_err_source_t @var{source}}, @w{int @var{err}})
652 The function @code{gcry_err_make_from_errno} is like
653 @code{gcry_err_make}, but it takes a system error like @code{errno}
654 instead of a @code{gcry_err_code_t} error code.
655 @end deftypefun
656
657 @deftypefun {gcry_error_t} gcry_error_from_errno (@w{int @var{err}})
658 The function @code{gcry_error_from_errno} is like @code{gcry_error},
659 but it takes a system error like @code{errno} instead of a
660 @code{gcry_err_code_t} error code.
661 @end deftypefun
662
663 Sometimes you might want to map system error numbers to error codes
664 directly, or map an error code representing a system error back to the
665 system error number.  The following functions can be used to do that.
666
667 @deftypefun {gcry_err_code_t} gcry_err_code_from_errno (@w{int @var{err}})
668 The function @code{gcry_err_code_from_errno} returns the error code
669 for the system error @var{err}.  If @var{err} is not a known system
670 error, the function returns @code{GPG_ERR_UNKNOWN_ERRNO}.
671 @end deftypefun
672
673 @deftypefun {int} gcry_err_code_to_errno (@w{gcry_err_code_t @var{err}})
674 The function @code{gcry_err_code_to_errno} returns the system error
675 for the error code @var{err}.  If @var{err} is not an error code
676 representing a system error, or if this system error is not defined on
677 this system, the function returns @code{0}.
678 @end deftypefun
679
680
681 @node Error Sources
682 @subsection Error Sources
683 @cindex error codes, list of
684
685 The library @code{libgpg-error} defines an error source for every
686 component of the GnuPG system.  The error source part of an error
687 value is not well defined.  As such it is mainly useful to improve the
688 diagnostic error message for the user.
689
690 If the error code part of an error value is @code{0}, the whole error
691 value will be @code{0}.  In this case the error source part is of
692 course @code{GPG_ERR_SOURCE_UNKNOWN}.
693
694 The list of error sources that might occur in applications using
695 @acronym{Libgctypt} is:
696
697 @table @code
698 @item GPG_ERR_SOURCE_UNKNOWN
699 The error source is not known.  The value of this error source is
700 @code{0}.
701
702 @item GPG_ERR_SOURCE_GPGME
703 The error source is @acronym{GPGME} itself.
704
705 @item GPG_ERR_SOURCE_GPG
706 The error source is GnuPG, which is the crypto engine used for the
707 OpenPGP protocol.
708
709 @item GPG_ERR_SOURCE_GPGSM
710 The error source is GPGSM, which is the crypto engine used for the
711 OpenPGP protocol.
712
713 @item GPG_ERR_SOURCE_GCRYPT
714 The error source is @code{libgcrypt}, which is used by crypto engines
715 to perform cryptographic operations.
716
717 @item GPG_ERR_SOURCE_GPGAGENT
718 The error source is @command{gpg-agent}, which is used by crypto
719 engines to perform operations with the secret key.
720
721 @item GPG_ERR_SOURCE_PINENTRY
722 The error source is @command{pinentry}, which is used by
723 @command{gpg-agent} to query the passphrase to unlock a secret key.
724
725 @item GPG_ERR_SOURCE_SCD
726 The error source is the SmartCard Daemon, which is used by
727 @command{gpg-agent} to delegate operations with the secret key to a
728 SmartCard.
729
730 @item GPG_ERR_SOURCE_KEYBOX
731 The error source is @code{libkbx}, a library used by the crypto
732 engines to manage local keyrings.
733
734 @item GPG_ERR_SOURCE_USER_1
735 @item GPG_ERR_SOURCE_USER_2
736 @item GPG_ERR_SOURCE_USER_3
737 @item GPG_ERR_SOURCE_USER_4
738 These error sources are not used by any GnuPG component and can be
739 used by other software.  For example, applications using
740 @acronym{Libgcrypt} can use them to mark error values coming from callback
741 handlers.  Thus @code{GPG_ERR_SOURCE_USER_1} is the default for errors
742 created with @code{gcry_error} and @code{gcry_error_from_errno},
743 unless you define @code{GCRY_ERR_SOURCE_DEFAULT} before including
744 @file{gcrypt.h}.
745 @end table
746
747
748 @node Error Codes
749 @subsection Error Codes
750 @cindex error codes, list of
751
752 The library @code{libgpg-error} defines many error values.  The
753 following list includes the most important error codes.
754
755 @table @code
756 @item GPG_ERR_EOF
757 This value indicates the end of a list, buffer or file.
758
759 @item GPG_ERR_NO_ERROR
760 This value indicates success.  The value of this error code is
761 @code{0}.  Also, it is guaranteed that an error value made from the
762 error code @code{0} will be @code{0} itself (as a whole).  This means
763 that the error source information is lost for this error code,
764 however, as this error code indicates that no error occured, this is
765 generally not a problem.
766
767 @item GPG_ERR_GENERAL
768 This value means that something went wrong, but either there is not
769 enough information about the problem to return a more useful error
770 value, or there is no separate error value for this type of problem.
771
772 @item GPG_ERR_ENOMEM
773 This value means that an out-of-memory condition occurred.
774
775 @item GPG_ERR_E...
776 System errors are mapped to GPG_ERR_EFOO where FOO is the symbol for
777 the system error.
778
779 @item GPG_ERR_INV_VALUE
780 This value means that some user provided data was out of range.
781
782 @item GPG_ERR_UNUSABLE_PUBKEY
783 This value means that some recipients for a message were invalid.
784
785 @item GPG_ERR_UNUSABLE_SECKEY
786 This value means that some signers were invalid.
787
788 @item GPG_ERR_NO_DATA
789 This value means that data was expected where no data was found.
790
791 @item GPG_ERR_CONFLICT
792 This value means that a conflict of some sort occurred.
793
794 @item GPG_ERR_NOT_IMPLEMENTED
795 This value indicates that the specific function (or operation) is not
796 implemented.  This error should never happen.  It can only occur if
797 you use certain values or configuration options which do not work,
798 but for which we think that they should work at some later time.
799
800 @item GPG_ERR_DECRYPT_FAILED
801 This value indicates that a decryption operation was unsuccessful.
802
803 @item GPG_ERR_WRONG_KEY_USAGE
804 This value indicates that a key is not used appropriately.
805
806 @item GPG_ERR_NO_SECKEY
807 This value indicates that no secret key for the user ID is available.
808
809 @item GPG_ERR_UNSUPPORTED_ALGORITHM
810 This value means a verification failed because the cryptographic
811 algorithm is not supported by the crypto backend.
812
813 @item GPG_ERR_BAD_SIGNATURE
814 This value means a verification failed because the signature is bad.
815
816 @item GPG_ERR_NO_PUBKEY
817 This value means a verification failed because the public key is not
818 available.
819
820 @item GPG_ERR_USER_1
821 @item GPG_ERR_USER_2
822 @item ...
823 @item GPG_ERR_USER_16
824 These error codes are not used by any GnuPG component and can be
825 freely used by other software.  Applications using @acronym{Libgcrypt}
826 might use them to mark specific errors returned by callback handlers
827 if no suitable error codes (including the system errors) for these
828 errors exist already.
829 @end table
830
831
832 @node Error Strings
833 @subsection Error Strings
834 @cindex error values, printing of
835 @cindex error codes, printing of
836 @cindex error sources, printing of
837 @cindex error strings
838
839 @deftypefun {const char *} gcry_strerror (@w{gcry_error_t @var{err}})
840 The function @code{gcry_strerror} returns a pointer to a statically
841 allocated string containing a description of the error code contained
842 in the error value @var{err}.  This string can be used to output a
843 diagnostic message to the user.
844 @end deftypefun
845
846
847 @deftypefun {const char *} gcry_strsource (@w{gcry_error_t @var{err}})
848 The function @code{gcry_strerror} returns a pointer to a statically
849 allocated string containing a description of the error source
850 contained in the error value @var{err}.  This string can be used to
851 output a diagnostic message to the user.
852 @end deftypefun
853
854 The following example illustrates the use of the functions described
855 above:
856
857 @example
858 @{
859   gcry_cipher_hd_t handle;
860   gcry_error_t err = 0;
861
862   err = gcry_cipher_open (&handle, GCRY_CIPHER_AES, GCRY_CIPHER_MODE_CBC, 0);
863   if (err)
864     @{
865       fprintf (stderr, "Failure: %s/%s\n",
866                gcry_strsource (err),
867                gcry_strerror (err));
868     @}
869 @}
870 @end example
871
872 @c **********************************************************
873 @c *******************  General  ****************************
874 @c **********************************************************
875 @node Handler Functions
876 @chapter Handler Functions
877
878 @acronym{Libgcrypt} makes it possible to install so called `handler functions',
879 which get called by @acronym{Libgcrypt} in case of certain events.
880
881 @menu
882 * Progress handler::            Using a progress handler function.
883 * Allocation handler::          Using special memory allocation functions.
884 * Error handler::               Using error handler functions.
885 * Logging handler::             Using a special logging function.
886 @end menu
887
888 @node Progress handler
889 @section Progress handler
890
891 It is often useful to retrieve some feedback while long running
892 operations are performed.
893
894 @deftp {Data type} gcry_handler_progress_t
895 Progress handler functions have to be of the type
896 @code{gcry_handler_progress_t}, which is defined as:
897
898 @code{void (*gcry_handler_progress_t) (void *, const char *, int, int, int)}
899 @end deftp
900
901 The following function may be used to register a handler function for
902 this purpose.
903
904 @deftypefun void gcry_set_progress_handler (gcry_handler_progress_t @var{cb}, void *@var{cb_data})
905
906 This function installs @var{cb} as the `Progress handler' function.
907 @var{cb} must be defined as follows:
908
909 @example
910 void
911 my_progress_handler (void *@var{cb_data}, const char *@var{what},
912                      int @var{printchar}, int @var{current}, int @var{total})
913 @{
914   /* Do something.  */
915 @}
916 @end example
917
918 A description of the arguments of the progress handler function follows.
919
920 @table @var
921 @item cb_data
922 The argument provided in the call to @code{gcry_set_progress_handler}.
923 @item what
924 A string identifying the type of the progress output.  The following
925 values for @var{what} are defined:
926
927 @table @code
928 @item need_entropy
929 Not enough entropy is available.  @var{total} holds the number of
930 required bytes.
931
932 @item primegen
933 Values for @var{printchar}:
934 @table @code
935 @item \n
936 Prime generated.
937 @item !
938 Need to refresh the pool of prime numbers.
939 @item <, >
940 Number of bits adjusted.
941 @item ^
942 Searching for a generator.
943 @item .
944 Fermat test on 10 candidates failed.
945 @item :
946 Restart with a new random value.
947 @item +
948 Rabin Miller test passed.
949 @end table
950
951 @end table
952
953 @end table
954 @end deftypefun
955
956 @node Allocation handler
957 @section Allocation handler
958
959 It is possible to make @acronym{Libgcrypt} use special memory
960 allocation functions instead of the built-in ones.
961
962 Memory allocation functions are of the following types:
963 @deftp {Data type} gcry_handler_alloc_t
964 This type is defined as: @code{void *(*gcry_handler_alloc_t) (size_t n)}.
965 @end deftp
966 @deftp {Data type} gcry_handler_secure_check_t
967 This type is defined as: @code{int *(*gcry_handler_secure_check_t) (const void *)}.
968 @end deftp
969 @deftp {Data type} gcry_handler_realloc_t
970 This type is defined as: @code{void *(*gcry_handler_realloc_t) (void *p, size_t n)}.
971 @end deftp
972 @deftp {Data type} gcry_handler_free_t
973 This type is defined as: @code{void *(*gcry_handler_free_t) (void *)}.
974 @end deftp
975
976 Special memory allocation functions can be installed with the
977 following function:
978
979 @deftypefun void gcry_set_allocation_handler (gcry_handler_alloc_t @var{func_alloc}, gcry_handler_alloc_t @var{func_alloc_secure}, gcry_handler_secure_check_t @var{func_secure_check}, gcry_handler_realloc_t @var{func_realloc}, gcry_handler_free_t @var{func_free})
980 Install the provided functions and use them instead of the built-in
981 functions for doing memory allocation.
982 @end deftypefun
983
984 @node Error handler
985 @section Error handler
986
987 The following functions may be used to register handler functions that
988 are called by @acronym{Libgcrypt} in case certain error conditions
989 occur.
990
991 @deftp {Data type} gcry_handler_no_mem_t
992 This type is defined as: @code{void (*gcry_handler_no_mem_t) (void *, size_t, unsigned int)}
993 @end deftp
994 @deftypefun void gcry_set_outofcore_handler (gcry_handler_no_mem_t @var{func_no_mem}, void *@var{cb_data})
995 This function registers @var{func_no_mem} as `out-of-core handler',
996 which means that it will be called in the case of not having enough
997 memory available.
998 @end deftypefun
999
1000 @deftp {Data type} gcry_handler_error_t
1001 This type is defined as: @code{void (*gcry_handler_error_t) (void *, int, const char *)}
1002 @end deftp
1003
1004 @deftypefun void gcry_set_fatalerror_handler (gcry_handler_error_t @var{func_error}, void *@var{cb_data})
1005 This function registers @var{func_error} as `error handler',
1006 which means that it will be called in error conditions.
1007 @end deftypefun
1008
1009 @node Logging handler
1010 @section Logging handler
1011
1012 @deftp {Data type} gcry_handler_log_t
1013 This type is defined as: @code{void (*gcry_handler_log_t) (void *, int, const char *, va_list)}
1014 @end deftp
1015
1016 @deftypefun void gcry_set_log_handler (gcry_handler_log_t @var{func_log}, void *@var{cb_data})
1017 This function registers @var{func_log} as `logging handler', which
1018 means that it will be called in case @acronym{Libgcrypt} wants to log
1019 a message.
1020 @end deftypefun
1021
1022 @c **********************************************************
1023 @c *******************  Ciphers  ****************************
1024 @c **********************************************************
1025 @c @include cipher-ref.texi
1026 @node Symmetric cryptography
1027 @chapter Symmetric cryptography
1028
1029 The cipher functions are used for symmetrical cryptography,
1030 i.e. cryptography using a shared key.  The programming model follows
1031 an open/process/close paradigm and is in that similar to other
1032 building blocks provided by @acronym{Libgcrypt}.
1033
1034 @menu
1035 * Available ciphers::           List of ciphers supported by the library.
1036 * Cipher modules::              How to work with cipher modules.
1037 * Available cipher modes::      List of cipher modes supported by the library.
1038 * Working with cipher handles::  How to perform operations related to cipher handles.
1039 * General cipher functions::    General cipher functions independent of cipher handles.
1040 @end menu
1041
1042 @node Available ciphers
1043 @section Available ciphers
1044
1045 @table @code
1046 @item GCRY_CIPHER_NONE
1047 This is not a real algorithm but used by some functions as error return.
1048 The value always evaluates to false.
1049
1050 @item GCRY_CIPHER_IDEA
1051 This is the IDEA algorithm.  The constant is provided but there is
1052 currently no implementation for it because the algorithm is patented.
1053
1054 @item GCRY_CIPHER_3DES
1055 Triple-DES with 3 Keys as EDE.  The key size of this algorithm is 168 but
1056 you have to pass 192 bits because the most significant bits of each byte
1057 are ignored.
1058
1059 @item GCRY_CIPHER_CAST5
1060 CAST128-5 block cipher algorithm.  The key size is 128 bits.
1061         
1062 @item GCRY_CIPHER_BLOWFISH
1063 The blowfish algorithm. The current implementation allows only for a key
1064 size of 128 bits.
1065
1066 @item GCRY_CIPHER_SAFER_SK128
1067 Reserved and not currently implemented.
1068
1069 @item GCRY_CIPHER_DES_SK          
1070 Reserved and not currently implemented.
1071  
1072 @item  GCRY_CIPHER_AES        
1073 @itemx GCRY_CIPHER_AES128
1074 @itemx GCRY_CIPHER_RIJNDAEL
1075 @itemx GCRY_CIPHER_RIJNDAEL128
1076 AES (Rijndael) with a 128 bit key.
1077
1078 @item  GCRY_CIPHER_AES192     
1079 @itemx GCRY_CIPHER_RIJNDAEL128
1080 AES (Rijndael) with a 192 bit key.
1081
1082 @item  GCRY_CIPHER_AES256 
1083 @itemx GCRY_CIPHER_RIJNDAEL256
1084 AES (Rijndael) with a 256 bit key.
1085     
1086 @item  GCRY_CIPHER_TWOFISH
1087 The Twofish algorithm with a 256 bit key.
1088     
1089 @item  GCRY_CIPHER_TWOFISH128
1090 The Twofish algorithm with a 128 bit key.
1091     
1092 @item  GCRY_CIPHER_ARCFOUR   
1093 An algorithm which is 100% compatible with RSA Inc.'s RC4 algorithm.
1094 Note that this is a stream cipher and must be used very carefully to
1095 avoid a couple of weaknesses. 
1096
1097 @item  GCRY_CIPHER_DES       
1098 Standard DES with a 56 bit key. You need to pass 64 bit but the high
1099 bits of each byte are ignored.  Note, that this is a weak algorithm
1100 which can be broken in reasonable time using a brute force approach.
1101
1102 @end table
1103
1104 @node Cipher modules
1105 @section Cipher modules
1106
1107 @acronym{Libgcrypt} makes it possible to load additional `cipher
1108 modules'; these cipher can be used just like the cipher algorithms
1109 that are built into the library directly.  For an introduction into
1110 extension modules, see @xref{Modules}.
1111
1112 @deftp {Data type} gcry_cipher_spec_t
1113 This is the `module specification structure' needed for registering
1114 cipher modules, which has to be filled in by the user before it can be
1115 used to register a module.  It contains the following members:
1116
1117 @table @code
1118 @item const char *name
1119 The primary name of the algorithm.
1120 @item const char **aliases
1121 A list of strings that are `aliases' for the algorithm.  The list must
1122 be terminated with a NULL element.
1123 @item gcry_cipher_oid_spec_t *oids
1124 A list of OIDs that are to be associated with the algorithm.  The
1125 list's last element must have it's `oid' member set to NULL.  See
1126 below for an explanation of this type.
1127 @item size_t blocksize
1128 The block size of the algorithm, in bytes.
1129 @item size_t keylen
1130 The length of the key, in bits.
1131 @item size_t contextsize
1132 The size of the algorithm-specific `context', that should be allocated
1133 for each handle.
1134 @item gcry_cipher_setkey_t setkey
1135 The function responsible for initializing a handle with a provided
1136 key.  See below for a description of this type.
1137 @item gcry_cipher_encrypt_t encrypt
1138 The function responsible for encrypting a single block.  See below for
1139 a description of this type.
1140 @item gcry_cipher_decrypt_t decrypt
1141 The function responsible for decrypting a single block.  See below for
1142 a description of this type.
1143 @item gcry_cipher_stencrypt_t stencrypt
1144 Like `encrypt', for stream ciphers.  See below for a description of
1145 this type.
1146 @item gcry_cipher_stdecrypt_t stdecrypt
1147 Like `decrypt', for stream ciphers.  See below for a description of
1148 this type.
1149 @end table
1150 @end deftp
1151
1152 @deftp {Data type} gcry_cipher_oid_spec_t
1153 This type is used for associating a user-provided algorithm
1154 implementation with certain OIDs.  It contains the following members:
1155 @table @code
1156 @item const char *oid
1157 Textual representation of the OID.
1158 @item int mode
1159 Cipher mode for which this OID is valid.
1160 @end table
1161 @end deftp
1162
1163 @deftp {Data type} gcry_cipher_setkey_t
1164 Type for the `setkey' function, defined as: gcry_err_code_t
1165 (*gcry_cipher_setkey_t) (void *c, const unsigned char *key, unsigned
1166 keylen)
1167 @end deftp
1168
1169 @deftp {Data type} gcry_cipher_encrypt_t
1170 Type for the `encrypt' function, defined as: gcry_err_code_t
1171 (*gcry_cipher_encrypt_t) (void *c, const unsigned char *outbuf, const
1172 unsigned char *inbuf)
1173 @end deftp
1174
1175 @deftp {Data type} gcry_cipher_decrypt_t
1176 Type for the `decrypt' function, defined as: gcry_err_code_t
1177 (*gcry_cipher_decrypt_t) (void *c, const unsigned char *outbuf, const
1178 unsigned char *inbuf)
1179 @end deftp
1180
1181 @deftp {Data type} gcry_cipher_stencrypt_t
1182 Type for the `stencrypt' function, defined as: gcry_err_code_t
1183 (*gcry_cipher_stencrypt_t) (void *c, const unsigned char *outbuf, const
1184 unsigned char *, unsigned int n)
1185 @end deftp
1186
1187 @deftp {Data type} gcry_cipher_stdecrypt_t
1188 Type for the `stdecrypt' function, defined as: gcry_err_code_t
1189 (*gcry_cipher_stdecrypt_t) (void *c, const unsigned char *outbuf, const
1190 unsigned char *, unsigned int n)
1191 @end deftp
1192
1193 @deftypefun gcry_error_t gcry_cipher_register (gcry_cipher_spec_t *@var{cipher}, unsigned int *algorithm_id, gcry_module_t *@var{module})
1194
1195 Register a new cipher module whose specification can be found in
1196 @var{cipher}.  On success, a new algorithm ID is stored in
1197 @var{algorithm_id} and a pointer representhing this module is stored
1198 in @var{module}.
1199 @end deftypefun
1200
1201 @deftypefun void gcry_cipher_unregister (gcry_module_t @var{module})
1202 Unregister the cipher identified by @var{module}, which must have been
1203 registered with gcry_cipher_register.
1204 @end deftypefun
1205
1206 @deftypefun gcry_error_t gcry_cipher_list (int *@var{list}, int *@var{list_length})
1207 Get a list consisting of the IDs of the loaded cipher modules.  If
1208 @var{list} is zero, write the number of loaded cipher modules to
1209 @var{list_length} and return.  If @var{list} is non-zero, the first
1210 *@var{list_length} algorithm IDs are stored in @var{list}, which must
1211 be of according size.  In case there are less cipher modules than
1212 *@var{list_length}, *@var{list_length} is updated to the correct
1213 number.
1214 @end deftypefun
1215
1216 @node Available cipher modes
1217 @section Available cipher modes
1218
1219 @table @code
1220 @item GCRY_CIPHER_MODE_NONE
1221 No mode specified, may be set later using other functions.  The value
1222 of this constant is always 0.
1223
1224 @item GCRY_CIPHER_MODE_ECB
1225 Electronic Codebook mode.  
1226
1227 @item GCRY_CIPHER_MODE_CFB
1228 Cipher Feedback mode.
1229
1230 @item  GCRY_CIPHER_MODE_CBC
1231 Cipher Block Chaining mode.
1232
1233 @item GCRY_CIPHER_MODE_STREAM
1234 Stream mode, only to be used with stream cipher algorithms.
1235
1236 @item GCRY_CIPHER_MODE_OFB
1237 Outer Feedback mode.
1238
1239 @item  GCRY_CIPHER_MODE_CTR
1240 Counter mode.
1241
1242 @end table
1243
1244 @node Working with cipher handles
1245 @section Working with cipher handles
1246
1247 To use a cipher algorithm, you must first allocate an according
1248 handle.  This is to be done using the open function:
1249
1250 @deftypefun gcry_error_t gcry_cipher_open (gcry_cipher_hd_t *@var{hd},
1251 int @var{algo}, int @var{mode}, unsigned int @var{flags})
1252
1253 This function creates the context handle required for most of the
1254 other cipher functions and returns a handle to it in `hd'.  In case of
1255 an error, an according error code is returned.
1256
1257 The ID of algorithm to use must be specified via @var{algo}.  See
1258 @xref{Available ciphers}, for a list of supported ciphers and the
1259 according constants.
1260
1261 Besides using the constants directly, the function
1262 @code{gcry_cipher_map_name} may be used to convert the textual name of
1263 an algorithm into the according numeric ID.
1264
1265 The cipher mode to use must be specified via @var{mode}.  See
1266 @xref{Available cipher modes}, for a list of supported cipher modes
1267 and the according constants.  Note, that some modes do not work
1268 together with all algorithms.
1269
1270 The third argument @var{flags} can either be passed as @code{0} or as
1271 the bit-wise OR of the following constants.
1272
1273 @table @code
1274 @item GCRY_CIPHER_SECURE
1275 Make sure that all operations are allocated in secure memory.  This is
1276 useful, when the key material is highly confidential.
1277 @item GCRY_CIPHER_ENABLE_SYNC
1278 This flag enables the CFB sync mode, which is a special feature of
1279 @acronym{Libgcrypt}'s CFB mode implementation to allow for OpenPGP's CFB variant. 
1280 See @code{gcry_cipher_sync}.
1281 @item GCRY_CIPHER_CBC_CTS
1282 Enable cipher text stealing (CTS) for the CBC mode.  Cannot be used
1283 simultaneous as GCRY_CIPHER_CBC_MAC
1284 @item GCRY_CIPHER_CBC_MAC
1285 Compute CBC-MAC keyed checksums.  This is the same as CBC mode, but
1286 only output the last block.  Cannot be used simultaneous as
1287 GCRY_CIPHER_CBC_CTS.
1288 @end table
1289 @end deftypefun 
1290
1291 Use the following function to release an existing handle:
1292
1293 @deftypefun void gcry_cipher_close (gcry_cipher_hd_t @var{h})
1294
1295 This function releases the context created by @code{gcry_cipher_open}.
1296 @end deftypefun
1297
1298 In order to use a handle for performing cryptographic operations, a
1299 `key' has to be set first:
1300
1301 @deftypefun gcry_error_t gcry_cipher_setkey (gcry_cipher_hd_t @var{h}, void *@var{k}, size_t @var{l})
1302
1303 Set the key @var{k} used for encryption or decryption in the context
1304 denoted by the handle @var{h}.  The length @var{l} of the key @var{k}
1305 must match the required length of the algorithm set for this context or
1306 be in the allowed range for algorithms with variable key size.  The
1307 function checks this and returns an error if there is a problem.  A
1308 caller should always check for an error.
1309
1310 Note, this is currently implemented as a macro but may be changed to a
1311 function in the future.
1312 @end deftypefun
1313
1314 Most crypto modes requires an initialization vector (IV), which
1315 usually is a non-secret random string acting as a kind of salt value.
1316 The CTR mode requires a counter, which is also similar to a salt
1317 value.  To set the IV or CTR, use these functions:
1318
1319 @deftypefun gcry_error_t gcry_cipher_setiv (gcry_cipher_hd_t @var{h}, void *@var{k}, size_t @var{l})
1320
1321 Set the initialization vector used for encryption or decryption. The
1322 vector is passed as the buffer @var{K} of length @var{l} and copied to
1323 internal data structures.  The function checks that the IV matches the
1324 requirement of the selected algorithm and mode.  Note, that this is
1325 implemented as a macro.
1326 @end deftypefun
1327
1328 @deftypefun gcry_error_t gcry_cipher_setctr (gcry_cipher_hd_t @var{h}, void *@var{c}, size_t @var{l})
1329
1330 Set the counter vector used for encryption or decryption. The counter
1331 is passed as the buffer @var{c} of length @var{l} and copied to
1332 internal data structures.  The function checks that the counter
1333 matches the requirement of the selected algorithm (i.e., it must be
1334 the same size as the block size).  Note, that this is implemented as a
1335 macro.
1336 @end deftypefun
1337
1338 @deftypefun gcry_error_t gcry_cipher_reset (gcry_cipher_hd_t @var{h})
1339
1340 Set the given handle's context back to the state it had after the last
1341 call to gcry_cipher_setkey and clear the initialization vector.
1342
1343 Note, that gcry_cipher_reset is implemented as a macro.
1344 @end deftypefun
1345
1346 The actual encryption and decryption is done by using one of the
1347 following functions.  They may be used as often as required to process
1348 all the data.
1349
1350 @deftypefun gcry_error_t gcry_cipher_encrypt (gcry_cipher_hd_t @var{h}, unsigned char *{out}, size_t @var{outsize}, const unsigned char *@var{in}, size_t @var{inlen})
1351
1352 @code{gcry_cipher_encrypt} is used to encrypt the data.  This function
1353 can either work in place or with two buffers.  It uses the cipher
1354 context already setup and described by the handle @var{h}.  There are 2
1355 ways to use the function: If @var{in} is passed as @code{NULL} and
1356 @var{inlen} is @code{0}, in-place encryption of the data in @var{out} or
1357 length @var{outsize} takes place.  With @var{in} being not @code{NULL},
1358 @var{inlen} bytes are encrypted to the buffer @var{out} which must have
1359 at least a size of @var{inlen}.  @var{outlen} must be set to the
1360 allocated size of @var{out}, so that the function can check that there
1361 is sufficient space. Note, that overlapping buffers are not allowed.
1362
1363 Depending on the selected algorithms and encryption mode, the length of
1364 the buffers must be a multiple of the block size.
1365
1366 The function returns @code{0} on success or an error code.
1367 @end deftypefun
1368
1369
1370 @deftypefun gcry_error_t gcry_cipher_decrypt (gcry_cipher_hd_t @var{h}, unsigned char *{out}, size_t @var{outsize}, const unsigned char *@var{in}, size_t @var{inlen})
1371
1372 @code{gcry_cipher_decrypt} is used to decrypt the data.  This function
1373 can either work in place or with two buffers.  It uses the cipher
1374 context already setup and described by the handle @var{h}.  There are 2
1375 ways to use the function: If @var{in} is passed as @code{NULL} and
1376 @var{inlen} is @code{0}, in-place decryption of the data in @var{out} or
1377 length @var{outsize} takes place.  With @var{in} being not @code{NULL},
1378 @var{inlen} bytes are decrypted to the buffer @var{out} which must have
1379 at least a size of @var{inlen}.  @var{outlen} must be set to the
1380 allocated size of @var{out}, so that the function can check that there
1381 is sufficient space. Note, that overlapping buffers are not allowed.
1382
1383 Depending on the selected algorithms and encryption mode, the length of
1384 the buffers must be a multiple of the block size.
1385
1386 The function returns @code{0} on success or an error code.
1387 @end deftypefun
1388
1389
1390 OpenPGP (as defined in RFC-2440) requires a special sync operation in
1391 some places, the following function is used for this:
1392
1393 @deftypefun gcry_error_t gcry_cipher_sync (gcry_cipher_hd_t @var{h})
1394
1395 Perform the OpenPGP sync operation on context @var{h}. Note, that this
1396 is a no-op unless the context was created with the flag
1397 @code{GCRY_CIPHER_ENABLE_SYNC}
1398 @end deftypefun
1399
1400 Some of the described functions are implemented as macros utilizing a
1401 catch-all control function.  This control function is rarely used
1402 directly but there is nothing which would inhibit it:
1403
1404 @deftypefun gcry_error_t gcry_cipher_ctl (gcry_cipher_hd_t @var{h}, int @var{cmd}, void *@var{buffer}, size_t @var{buflen})
1405
1406 @code{gcry_cipher_ctl} controls various aspects of the cipher module and
1407 specific cipher contexts.  Usually some more specialized functions or
1408 macros are used for this purpose.  The semantics of the function and its
1409 parameters depends on the the command @var{cmd} and the passed context
1410 handle @var{h}.  Please see the comments in the source code
1411 (@code{src/global.c}) for details.
1412 @end deftypefun
1413
1414 @deftypefun gcry_error_t gcry_cipher_info (gcry_cipher_hd_t @var{h}, int @var{what}, void *@var{buffer}, size_t *@var{nbytes})
1415
1416 @code{gcry_cipher_info} is used to retrieve various
1417 information about a cipher context or the cipher module in general.
1418
1419 Currently no information is available.
1420 @end deftypefun
1421
1422 @node General cipher functions
1423 @section General cipher functions
1424
1425 To work with the algorithms, several functions are available to map
1426 algorithm names to the internal identifiers, as well as ways to
1427 retrieve information about an algorithm or the current cipher context.
1428
1429 @deftypefun gcry_error_t gcry_cipher_algo_info (int @var{algo}, int @var{what}, void *@var{buffer}, size_t *@var{nbytes})
1430
1431 This function is used to retrieve information on a specific algorithm.
1432 You pass the cipher algorithm ID as @var{algo} and the type of
1433 information requested as @var{what}. The result is either returned as
1434 the return code of the function or copied to the provided @var{buffer}
1435 whose allocated length must be available in an integer variable with the
1436 address passed in @var{nbytes}.  This variable will also receive the
1437 actual used length of the buffer. 
1438
1439 Here is a list of supported codes for @var{what}:
1440
1441 @c begin constants for gcry_cipher_algo_info
1442 @table @code
1443 @item GCRYCTL_GET_KEYLEN:
1444 Return the length of the key. If the algorithm supports multiple key
1445 lengths, the maximum supported value is returned.  The length is
1446 returned as number of octets (bytes) and not as number of bits in
1447 @var{nbytes}; @var{buffer} must be zero.
1448
1449 @item GCRYCTL_GET_BLKLEN:
1450 Return the block length of the algorithm.  The length is returned as a
1451 number of octets in @var{nbytes}; @var{buffer} must be zero.
1452
1453 @item GCRYCTL_TEST_ALGO:
1454 Returns @code{0} when the specified algorithm is available for use.
1455 @var{buffer} and @var{nbytes} must be zero.
1456  
1457 @end table  
1458 @c end constants for gcry_cipher_algo_info
1459
1460 @end deftypefun
1461 @c end gcry_cipher_algo_info
1462
1463 @deftypefun const char *gcry_cipher_algo_name (int @var{algo})
1464
1465 @code{gcry_cipher_algo_name} returns a string with the name of the
1466 cipher algorithm @var{algo}.  If the algorithm is not known or another
1467 error occurred, an empty string is returned.  This function will never
1468 return @code{NULL}.
1469 @end deftypefun
1470
1471 @deftypefun int gcry_cipher_map_name (const char *@var{name})
1472
1473 @code{gcry_cipher_map_name} returns the algorithm identifier for the
1474 cipher algorithm described by the string @var{name}.  If this algorithm
1475 is not available @code{0} is returned.
1476 @end deftypefun
1477
1478 @deftypefun int gcry_cipher_mode_from_oid (const char *@var{string})
1479
1480 Return the cipher mode associated with an @acronym{ASN.1} object
1481 identifier.  The object identifier is expected to be in the
1482 @acronym{IETF}-style dotted decimal notation.  The function returns
1483 @code{0} for an unknown object identifier or when no mode is associated
1484 with it.
1485 @end deftypefun
1486
1487
1488 @c **********************************************************
1489 @c *******************  Hash Functions  *********************
1490 @c **********************************************************
1491 @node Hashing
1492 @chapter Hashing
1493
1494 @acronym{Libgcrypt} provides an easy and consistent to use interface
1495 for hashing.  Hashing is buffered and several hash algorithms can be
1496 updated at once.  It is possible to calculate a MAC using the same
1497 routines.  The programming model follows an open/process/close
1498 paradigm and is in that similar to other building blocks provided by
1499 @acronym{Libgcrypt}.
1500
1501 For convenience reasons, a few cyclic redudancy check value operations
1502 are also supported.
1503
1504 @menu
1505 * Available hash algorithms::   List of hash algorithms supported by the library.
1506 * Hash algorithm modules::      How to work with hash algorithm modules.
1507 * Working with hash algorithms::  List of functions related to hashing.
1508 @end menu
1509
1510 @node Available hash algorithms
1511 @section Available hash algorithms
1512
1513 @c begin table of hash algorithms
1514 @table @code
1515 @item GCRY_MD_NONE
1516 This is not a real algorithm but used by some functions as an error
1517 return value.  This constant is guaranteed to have the value @code{0}.
1518
1519 @item GCRY_MD_SHA1
1520 This is the SHA-1 algorithm which yields a message digest of 20 bytes.
1521
1522 @item GCRY_MD_RMD160
1523 This is the 160 bit version of the RIPE message digest (RIPE-MD-160).
1524 Like SHA-1 it also yields a digest of 20 bytes.
1525
1526 @item GCRY_MD_MD5
1527 This is the well known MD5 algorithm, which yields a message digest of
1528 16 bytes. 
1529
1530 @item GCRY_MD_MD4
1531 This is the MD4 algorithm, which yields a message digest of 16 bytes.
1532
1533 @item GCRY_MD_MD2
1534 This is an reserved identifier for MD-2; there is no implementation yet.
1535
1536 @item GCRY_MD_TIGER
1537 This is the TIGER/192 algorithm which yields a message digest of 24 bytes.
1538
1539 @item GCRY_MD_HAVAL
1540 This is an reserved for the HAVAL algorithm with 5 passes and 160
1541 bit. It yields a message digest of 20 bytes.  Note that there is no
1542 implementation yet available.
1543
1544 @item GCRY_MD_SHA256
1545 This is the SHA-256 algorithm which yields a message digest of 32 bytes.
1546 See FIPS 180-2 for the specification.
1547
1548 @item GCRY_MD_SHA384
1549 This is reserved for SHA-2 with 384 bits. It yields a message digest of
1550 48 bytes.  Note that there is no implementation yet available.
1551
1552 @item GCRY_MD_SHA512
1553 This is reserved for SHA-2 with 512 bits. It yields a message digest of
1554 64 bytes.  Note that there is no implementation yet available.
1555
1556 @item GCRY_MD_CRC32
1557 This is the ISO 3309 and ITU-T V.42 cyclic redundancy check.  It
1558 yields an output of 4 bytes.
1559
1560 @item GCRY_MD_CRC32_RFC1510
1561 This is the above cyclic redundancy check function, as modified by RFC
1562 1510.  It yields an output of 4 bytes.
1563
1564 @item GCRY_MD_CRC24_RFC2440
1565 This is the OpenPGP cyclic redundancy check function.  It yields an
1566 output of 3 bytes.
1567
1568 @end table
1569 @c end table of hash algorithms
1570
1571 @node Hash algorithm modules
1572 @section Hash algorithm modules
1573
1574 @acronym{Libgcrypt} makes it possible to load additional `message
1575 digest modules'; these cipher can be used just like the message digest
1576 algorithms that are built into the library directly.  For an
1577 introduction into extension modules, see @xref{Modules}.
1578
1579 @deftp {Data type} gcry_md_spec_t
1580 This is the `module specification structure' needed for registering
1581 message digest modules, which has to be filled in by the user before
1582 it can be used to register a module.  It contains the following
1583 members:
1584
1585 @table @code
1586 @item const char *name
1587 The primary name of this algorithm.
1588 @item unsigned char *asnoid
1589 Array of bytes that form the ASN OID.
1590 @item int asnlen
1591 Length of bytes in `asnoid'.
1592 @item gcry_md_oid_spec_t *oids
1593 A list of OIDs that are to be associated with the algorithm.  The
1594 list's last element must have it's `oid' member set to NULL.  See
1595 below for an explanation of this type.  See below for an explanation
1596 of this type.
1597 @item int mdlen
1598 Length of the message digest algorithm.  See below for an explanation
1599 of this type.
1600 @item gcry_md_init_t init
1601 The function responsible for initializing a handle.  See below for an
1602 explanation of this type.
1603 @item gcry_md_write_t write
1604 The function responsible for writing data into a message digest
1605 context.  See below for an explanation of this type.
1606 @item gcry_md_final_t final
1607 The function responsible for `finalizing' a message digest context.
1608 See below for an explanation of this type.
1609 @item gcry_md_read_t read
1610 The function reponsible for reading out a message digest result.  See
1611 below for an explanation of this type.
1612 @item size_t contextsize
1613 The size of the algorithm-specific `context', that should be
1614 allocated for each handle.
1615 @end table
1616 @end deftp
1617
1618 @deftp {Data type} gcry_md_oid_spec_t
1619 This type is used for associating a user-provided algorithm
1620 implementation with certain OIDs.  It contains the following members:
1621
1622 @table @code
1623 @item const char *oidstring
1624 Textual representation of the OID.
1625 @end table
1626 @end deftp
1627
1628 @deftp {Data type} gcry_md_init_t
1629 Type for the `init' function, defined as: void (*gcry_md_init_t) (void
1630 *c)
1631 @end deftp
1632
1633 @deftp {Data type} gcry_md_write_t
1634 Type for the `write' function, defined as: void (*gcry_md_write_t)
1635 (void *c, unsigned char *buf, size_t nbytes)
1636 @end deftp
1637
1638 @deftp {Data type} gcry_md_final_t
1639 Type for the `final' function, defined as: void (*gcry_md_final_t)
1640 (void *c)
1641 @end deftp
1642
1643 @deftp {Data type} gcry_md_read_t
1644 Type for the `read' function, defined as: unsigned char
1645 *(*gcry_md_read_t) (void *c)
1646 @end deftp
1647
1648 @deftypefun gcry_error_t gcry_md_register (gcry_md_spec_t *@var{digest}, unsigned int *algorithm_id, gcry_module_t *@var{module})
1649
1650 Register a new digest module whose specification can be found in
1651 @var{digest}.  On success, a new algorithm ID is stored in
1652 @var{algorithm_id} and a pointer representhing this module is stored
1653 in @var{module}.
1654 @end deftypefun
1655
1656 @deftypefun void gcry_md_unregister (gcry_module_t @var{module})
1657 Unregister the digest identified by @var{module}, which must have been
1658 registered with gcry_md_register.
1659 @end deftypefun
1660
1661 @deftypefun gcry_error_t gcry_md_list (int *@var{list}, int *@var{list_length})
1662 Get a list consisting of the IDs of the loaded message digest modules.
1663 If @var{list} is zero, write the number of loaded message digest
1664 modules to @var{list_length} and return.  If @var{list} is non-zero,
1665 the first *@var{list_length} algorithm IDs are stored in @var{list},
1666 which must be of according size.  In case there are less message
1667 digests modules than *@var{list_length}, *@var{list_length} is updated
1668 to the correct number.
1669 @end deftypefun
1670
1671 @node Working with hash algorithms
1672 @section Working with hash algorithms
1673
1674 To use most of these function it is necessary to create a context;
1675 this is done using:
1676
1677 @deftypefun gcry_error_t gcry_md_open (gcry_md_hd_t *@var{hd}, int @var{algo}, unsigned int @var{flags})
1678
1679 Create a message digest object for algorithm @var{algo}.  @var{flags}
1680 may be given as an bitwise OR of constants described below.  @var{algo}
1681 may be given as @code{0} if the algorithms to use are later set using
1682 @code{gcry_md_enable}. @var{hd} is guaranteed to either receive a valid
1683 handle or NULL.
1684
1685 For a list of supported algorithms, see @xref{Available hash
1686 algorithms}.
1687
1688 The flags allowed for @var{mode} are:
1689
1690 @c begin table of hash flags
1691 @table @code
1692 @item GCRY_MD_FLAG_SECURE
1693 Allocate all buffers and the resulting digest in "secure memory".  Use
1694 this is the hashed data is highly confidential.
1695
1696 @item GCRY_MD_FLAG_HMAC
1697 Turn the algorithm into a HMAC message authentication algorithm.  This
1698 does only work if just one algorithm is enabled for the handle and
1699 SHA-384 and SHA512 is not used.  Note that the function
1700 @code{gcry_md_setkey} must be used set the MAC key.  If you want CBC
1701 message authentication codes based on a cipher, see @xref{Working with
1702 cipher handles}.
1703
1704 @end table
1705 @c begin table of hash flags
1706
1707 You may use the function @code{gcry_md_is_enabled} to later check
1708 whether an algorithm has been enabled.
1709
1710 @end deftypefun
1711 @c end function gcry_md_open
1712
1713 If you want to calculate several hash algorithms at the same time, you
1714 have to use the following function right after the @code{gcry_md_open}:
1715
1716 @deftypefun gcry_error_t gcry_md_enable (gcry_md_hd_t @var{h}, int @var{algo})
1717
1718 Add the message digest algorithm @var{algo} to the digest object
1719 described by handle @var{h}.  Duplicated enabling of algorithms is
1720 detected and ignored.
1721 @end deftypefun
1722
1723 If the flag @code{GCRY_MD_FLAG_HMAC} was used, the key for the MAC must
1724 be set using the function:
1725
1726 @deftypefun gcry_error_t gcry_md_setkey (gcry_md_hd_t @var{h}, const void *@var{key},
1727 size_t @var{keylen})
1728
1729 For use with the HMAC feature, set the MAC key to the value of @var{key}
1730 of length @var{keylen}.
1731 @end deftypefun
1732
1733
1734 After you are done with the hash calculation, you should release the
1735 resources by using:
1736
1737 @deftypefun void gcry_md_close (gcry_md_hd_t @var{h})
1738
1739 Release all resources of hash context @var{h}.  @var{h} should not be
1740 used after a call to this function.  A @code{NULL} passed as @var{h} is
1741 ignored.
1742
1743 @end deftypefun
1744
1745 Often you have to do several hash operations using the same algorithm.
1746 To avoid the overhead of creating and releasing context, a reset function
1747 is provided:
1748
1749 @deftypefun void gcry_md_reset (gcry_md_hd_t @var{h})
1750
1751 Reset the current context to its initial state.  This is effectively
1752 identical to a close followed by an open and enabling all currently
1753 active algorithms.
1754 @end deftypefun
1755
1756
1757 Often it is necessary to start hashing some data and than continue to
1758 hash different data.  To avoid hashing the same data several times (which
1759 might not even be possible if the data is received from a pipe), a
1760 snapshot of the current hash context can be taken and turned into a new
1761 context:
1762
1763 @deftypefun gcry_error_t gcry_md_copy (gcry_md_hd_t *@var{handle_dst}, gcry_md_hd_t @var{handle_src})
1764
1765 Create a new digest object as an exact copy of the object described by
1766 handle @var{handle_src} and store it in @var{handle_dst}.  The context
1767 is not reset and you can continue to hash data using this context and
1768 independently using the original context.
1769 @end deftypefun
1770
1771
1772 Now that we have prepared everything to calculate hashes, its time to
1773 see how it is actually done.  There are 2  ways for this, one to
1774 update the hash with a block of memory and one macro to update the hash
1775 by just one character.  Both may be used intermixed.
1776
1777 @deftypefun void gcry_md_write (gcry_md_hd_t @var{h}, const void *@var{buffer}, size_t @var{length})
1778
1779 Pass @var{length} bytes of the data in @var{buffer} to the digest object
1780 with handle @var{h} to update the digest values. This
1781 function should be used for large blocks of data.
1782 @end deftypefun
1783
1784 @deftypefun void gcry_md_putc (gcry_md_hd_t @var{h}, int @var{c})
1785
1786 Pass the byte in @var{c} to the digest object with handle @var{h} to
1787 update the digest value.  This is an efficient function, implemented as
1788 a macro to buffer the data before an actual update. 
1789 @end deftypefun
1790
1791 The semantics of the hash functions don't allow to read out intermediate
1792 message digests because the calculation must be finalized fist.  This
1793 finalization may for example include the number of bytes hashed in the
1794 message digest.  
1795
1796 @deftypefun void gcry_md_final (gcry_md_hd_t @var{h})
1797
1798 Finalize the message digest calculation.  This is not really needed
1799 because @code{gcry_md_read} does this implicitly.  After this has been
1800 done no further updates (by means of @code{gcry_md_write} or
1801 @code{gcry_md_putc} are allowed.  Only the first call to this function
1802 has an effect. It is implemented as a macro.
1803 @end deftypefun
1804
1805 The way to read out the calculated message digest is by using the
1806 function:
1807
1808 @deftypefun unsigned char *gcry_md_read (gcry_md_hd_t @var{h}, int @var{algo})
1809
1810 @code{gcry_md_read} returns the message digest after finalizing the
1811 calculation.  This function may be used as often as required but it will
1812 always return the same value for one handle.  The returned message digest
1813 is allocated within the message context and therefore valid until the
1814 handle is released or reseted (using @code{gcry_md_close} or
1815 @code{gcry_md_reset}.  @var{algo} may be given as 0 to return the only
1816 enabled message digest or it may specify one of the enabled algorithms.
1817 The function does return @code{NULL} if the requested algorithm has not
1818 been enabled.
1819 @end deftypefun
1820
1821 Because it is often necessary to get the message digest of one block of
1822 memory, a fast convenience function is available for this task: 
1823
1824 @deftypefun void gcry_md_hash_buffer (int @var{algo}, void *@var{digest}, const cvoid *@var{buffer}, size_t @var{length});
1825
1826 @code{gcry_md_hash_buffer} is a shortcut function to calculate a message
1827 digest of a buffer.  This function does not require a context and
1828 immediately returns the message digest of the @var{length} bytes at
1829 @var{buffer}.  @var{digest} must be allocated by the caller, large
1830 enough to hold the message digest yielded by the the specified algorithm
1831 @var{algo}.  This required size may be obtained by using the function
1832 @code{gcry_md_get_algo_dlen}.
1833
1834 Note, that this function will abort the process if an unavailable
1835 algorithm is used.
1836 @end deftypefun
1837
1838 @c ***********************************
1839 @c ***** MD info functions ***********
1840 @c ***********************************
1841
1842 Hash algorithms are identified by internal algorithm numbers (see
1843 @code{gcry_md_open} for a list.  However, in most applications they are
1844 used by names, so 2 functions are available to map between string
1845 representations and hash algorithm identifiers.
1846
1847 @deftypefun const char *gcry_md_algo_name (int @var{algo})
1848
1849 Map the digest algorithm id @var{algo} to a string representation of the
1850 algorithm name.  For unknown algorithms this functions returns an
1851 empty string.  This function should not be used to test for the
1852 availability of an algorithm.
1853 @end deftypefun
1854
1855 @deftypefun int gcry_md_map_name (const char *@var{name})
1856
1857 Map the algorithm with @var{name} to a digest algorithm identifier.
1858 Returns 0 if the algorithm name is not known.  Names representing
1859 @acronym{ASN.1} object identifiers are recognized if the @acronym{IETF}
1860 dotted format is used and the OID is prefixed with either "@code{oid.}"
1861 or "@code{OID.}".  For a list of supported OIDs, see the source code at
1862 @file{cipher/md.c}. This function should not be used to test for the
1863 availability of an algorithm.
1864 @end deftypefun
1865
1866 @deftypefun gcry_error_t gcry_md_get_asnoid (int @var{algo}, void *@var{buffer}, size_t *@var{length})
1867
1868 Return an DER encoded ASN.1 OID for the algorithm @var{algo} in the
1869 user allocated @var{buffer}. @var{length} must point to variable with
1870 the available size of @var{buffer} and receives after return the
1871 actual size of the returned OID.  The returned error code may be
1872 @code{GPG_ERR_TOO_SHORT} if the provided buffer is to short to receive
1873 the OID; it is possible to call the function with @code{NULL} for
1874 @var{buffer} to have it only return the required size.  The function
1875 returns 0 on success.
1876
1877 @end deftypefun
1878
1879
1880 To test whether an algorithm is actually available for use, the
1881 following macro should be used:
1882
1883 @deftypefun gcry_error_t gcry_md_test_algo (int @var{algo}) 
1884
1885 The macro returns 0 if the algorithm @var{algo} is available for use.
1886 @end deftypefun
1887
1888 If the length of a message digest is not known, it can be retrieved
1889 using the following function:
1890
1891 @deftypefun unsigned int gcry_md_get_algo_dlen (int @var{algo})
1892
1893 Retrieve the length in bytes of the digest yielded by algorithm
1894 @var{algo}.  This is often used prior to @code{gcry_md_read} to allocate
1895 sufficient memory for the digest.
1896 @end deftypefun
1897
1898
1899 In some situations it might be hard to remember the algorithm used for
1900 the ongoing hashing. The following function might be used to get that
1901 information:
1902
1903 @deftypefun int gcry_md_get_algo (gcry_md_hd_t @var{h})
1904
1905 Retrieve the algorithm used with the handle @var{h}. Note, that this
1906 does not work reliable if more than one algorithm is enabled in @var{h}.
1907 @end deftypefun
1908
1909 The following macro might also be useful:
1910
1911 @deftypefun int gcry_md_is_secure (gcry_md_hd_t @var{h})
1912
1913 This function returns true when the digest object @var{h} is allocated
1914 in "secure memory"; i.e. @var{h} was created with the
1915 @code{GCRY_MD_FLAG_SECURE}.
1916 @end deftypefun
1917
1918 @deftypefun int gcry_md_is_enabled (gcry_md_hd_t @var{h}, int @var{algo})
1919
1920 This function returns true when the algorithm @var{algo} has been
1921 enabled for the digest object @var{h}.
1922 @end deftypefun
1923
1924
1925
1926 Tracking bugs related to hashing is often a cumbersome task which
1927 requires to add a lot of printf statements into the code.  @acronym{Libgcrypt}
1928 provides an easy way to avoid this.  The actual data hashed can be
1929 written to files on request.  The following 2 macros should be used to
1930 implement such a debugging facility:
1931
1932 @deftypefun void gcry_md_start_debug (gcry_md_hd_t @var{h}, const char *@var{suffix})
1933
1934 Enable debugging for the digest object with handle @var{h}.  This
1935 creates create files named @file{dbgmd-<n>.<string>} while doing the
1936 actual hashing.  @var{suffix} is the string part in the filename.  The
1937 number is a counter incremented for each new hashing.  The data in the
1938 file is the raw data as passed to @code{gcry_md_write} or
1939 @code{gcry_md_putc}.
1940 @end deftypefun
1941
1942
1943 @deftypefun void gcry_md_stop_debug (gcry_md_hd_t @var{h}, int @var{reserved})
1944
1945 Stop debugging on handle @var{h}.  @var{reserved} should be specified as
1946 0.  This function is usually not required because @code{gcry_md_close}
1947 does implicitly stop debugging.
1948 @end deftypefun
1949
1950
1951 @c **********************************************************
1952 @c *******************  Public Key  *************************
1953 @c **********************************************************
1954 @node Public Key cryptography (I)
1955 @chapter Public Key cryptography (I)
1956
1957 Public key cryptography, also known as asymmetric cryptography, is an
1958 easy way for key management and to provide digital signatures.
1959 @acronym{Libgcrypt} provides two completely different interfaces to
1960 public key cryptography, this chapter explains the one based on
1961 S-expressions.
1962
1963 @menu
1964 * Available algorithms::        Algorithms supported by the library.
1965 * Used S-expressions::          Introduction into the used S-expression.
1966 * Public key modules::          How to work with public key modules.
1967 * Cryptographic Functions::     Functions for performing the cryptographic actions.
1968 * General public-key related Functions::  General functions, not implementing any cryptography.
1969 @end menu
1970
1971 @node Available algorithms
1972 @section Available algorithms
1973
1974 @acronym{Libgcrypt} supports the RSA (Rivest-Shamir-Adleman) algorithms as well
1975 as DSA (Digital Signature Algorithm) and ElGamal.  The versatile
1976 interface allows to add more algorithms in the future.
1977
1978 @node Used S-expressions
1979 @section Used S-expressions
1980
1981 @acronym{Libgcrypt}'s API for asymmetric cryptography is based on data
1982 structures called S-expressions (see XXXX) and does not work with
1983 contexts as most of the other building blocks of @acronym{Libgcrypt}
1984 do.
1985
1986 The following information are stored in S-expressions:
1987
1988 @table @asis
1989 @item keys
1990
1991 @item plain text data
1992
1993 @item encrypted data
1994
1995 @item signatures
1996
1997 @end table
1998
1999 @noindent
2000 To describe how @acronym{Libgcrypt} expect keys, we use some examples. Note that
2001 words in
2002 @ifnottex
2003 uppercase
2004 @end ifnottex
2005 @iftex
2006 italics
2007 @end iftex
2008 indicate parameters whereas lowercase words are literals.
2009
2010 @example
2011 (private-key
2012   (dsa
2013     (p @var{p-mpi})
2014     (q @var{q-mpi})
2015     (g @var{g-mpi})
2016     (y @var{y-mpi})
2017     (x @var{x-mpi})))
2018 @end example
2019
2020 @noindent
2021 This specifies a DSA private key with the following parameters:
2022
2023 @table @var
2024 @item p-mpi
2025 DSA prime @math{p}.
2026 @item q-mpi
2027 DSA group order @math{q} (which is a prime divisor of @math{p-1}).
2028 @item g-mpi
2029 DSA group generator @math{g}.
2030 @item y-mpi
2031 DSA public key value @math{y = g^x \bmod p}.
2032 @item x-mpi
2033 DSA secret exponent x.
2034 @end table
2035
2036 All the MPI values are  expected to be in @code{GCRYMPI_FMT_USG} format.
2037 The public key is similar with "private-key" replaced by "public-key"
2038 and no @var{x-mpi}.
2039
2040 An easy way to create such an S-expressions is by using
2041 @code{gcry_sexp_build} which allows to pass a string with printf-like
2042 escapes to insert MPI values.
2043
2044 @noindent
2045 Here is an example for an RSA key:
2046
2047 @example
2048 (private-key
2049   (rsa
2050     (n @var{n-mpi})
2051     (e @var{e-mpi})
2052     (d @var{d-mpi})
2053     (p @var{p-mpi})
2054     (q @var{q-mpi})
2055     (u @var{u-mpi})
2056 @end example
2057
2058 @noindent
2059 with
2060
2061 @table @var
2062 @item n-mpi
2063 RSA public modulus @math{n}.
2064 @item e-mpi
2065 RSA public exponent @math{e}.
2066 @item d-mpi
2067 RSA secret exponent @math{d = e^{-1} \bmod (p-1)(q-1)}.
2068 @item p-mpi
2069 RSA secret prime @math{p}.
2070 @item q-mpi
2071 RSA secret prime @math{q} with @math{q > p}.
2072 @item u-mpi
2073 multiplicative inverse @math{u = p^{-1} \bmod q}.
2074 @end table
2075
2076 @node Public key modules
2077 @section Public key modules
2078
2079 @acronym{Libgcrypt} makes it possible to load additional `public key
2080 modules'; these public key algorithms can be used just like the
2081 algorithms that are built into the library directly.  For an
2082 introduction into extension modules, see @xref{Modules}.
2083
2084 @deftp {Data type} gcry_pk_spec_t
2085 This is the `module specification structure' needed for registering
2086 public key modules, which has to be filled in by the user before it
2087 can be used to register a module.  It contains the following members:
2088
2089 @table @code
2090 @item const char *name
2091 The primary name of this algorithm.
2092 @item char **aliases
2093 A list of strings that are `aliases' for the algorithm.  The list
2094 musdt be terminanted with a NULL element.
2095 @item const char *elements_pkey
2096 String containing the one-letter names of the MPI values contained in
2097 a public key.
2098 @item const char *element_skey
2099 String containing the one-letter names of the MPI values contained in
2100 a secret key.
2101 @item const char *elements_enc
2102 String containing the one-letter names of the MPI values that are the
2103 result of an encryption operation using this algorithm.
2104 @item const char *elements_sig
2105 String containing the one-letter names of the MPI values that are the
2106 result of a sign operation using this algorithm.
2107 @item const char *elements_grip
2108 String containing the one-letter names of the MPI values that are to
2109 be included in the `key grip'.
2110 @item int use
2111 The bitwise-OR of the following flags, depending on the abilities of
2112 the algortihm:
2113 @table @code
2114 @item GCRY_PK_USAGE_SIGN
2115 The algorithm supports signing and verifying of data.
2116 @item GCRY_PK_USAGE_ENCR
2117 The algorithm supports the encryption and decryption of data.
2118 @end table
2119 @item gcry_pk_generate_t generate
2120 The function responsible for generating a new key pair.  See below for
2121 a description of this type.
2122 @item gcry_pk_check_secret_key_t check_secret_key
2123 The function responsible for checking the sanity of a provided secret
2124 key.  See below for a description of this type.
2125 @item gcry_pk_encrypt_t encrypt
2126 The function responsible for encrypting data.  See below for a
2127 description of this type.
2128 @item gcry_pk_decrypt_t decrypt
2129 The function responsible for decrypting data.  See below for a
2130 description of this type.
2131 @item gcry_pk_sign_t sign
2132 The function reponsible for signing data.  See below for a description
2133 of this type.
2134 @item gcry_pk_verify_t verify
2135 The function responsible for verifying that the provided signature
2136 matches the provided data.  See below for a description of this type.
2137 @item gcry_pk_get_nbits_t get_nbits
2138 The function reponsible for returning the number of bits of a provided
2139 key.  See below for a description of this type.
2140 @end table
2141 @end deftp
2142
2143 @deftp {Data type} gcry_pk_generate_t
2144 Type for the `generate' function, defined as: gcry_err_code_t
2145 (*gcry_pk_generate_t) (int algo, unsigned int nbits, unsigned long
2146 use_e, gcry_mpi_t *skey, gcry_mpi_t **retfactors)
2147 @end deftp
2148
2149 @deftp {Data type} gcry_pk_check_secret_key_t
2150 Type for the `check_secret_key' function, defined as: gcry_err_code_t
2151 (*gcry_pk_check_secret_key_t) (int algo, gcry_mpi_t *skey)
2152 @end deftp
2153
2154 @deftp {Data type} gcry_pk_encrypt_t
2155 Type for the `encrypt' function, defined as: gcry_err_code_t
2156 (*gcry_pk_encrypt_t) (int algo, gcry_mpi_t *resarr, gcry_mpi_t data,
2157 gcry_mpi_t *pkey, int flags)
2158 @end deftp
2159
2160 @deftp {Data type} gcry_pk_decrypt_t
2161 Type for the `decrypt' function, defined as: gcry_err_code_t
2162 (*gcry_pk_decrypt_t) (int algo, gcry_mpi_t *result, gcry_mpi_t *data,
2163 gcry_mpi_t *skey, int flags)
2164 @end deftp
2165
2166 @deftp {Data type} gcry_pk_sign_t
2167 Type for the `sign' function, defined as: gcry_err_code_t
2168 (*gcry_pk_sign_t) (int algo, gcry_mpi_t *resarr, gcry_mpi_t data,
2169 gcry_mpi_t *skey)
2170 @end deftp
2171
2172 @deftp {Data type} gcry_pk_verify_t
2173 Type for the `verify' function, defined as: gcry_err_code_t
2174 (*gcry_pk_verify_t) (int algo, gcry_mpi_t hash, gcry_mpi_t *data,
2175 gcry_mpi_t *pkey, int (*cmp) (void *, gcry_mpi_t), void *opaquev)
2176 @end deftp
2177
2178 @deftp {Data type} gcry_pk_get_nbits_t
2179 Type for the `get_nbits' function, defined as: unsigned
2180 (*gcry_pk_get_nbits_t) (int algo, gcry_mpi_t *pkey)
2181 @end deftp
2182
2183 @deftypefun gcry_error_t gcry_pk_register (gcry_pk_spec_t *@var{pubkey}, unsigned int *algorithm_id, gcry_module_t *@var{module})
2184
2185 Register a new public key module whose specification can be found in
2186 @var{pubkey}.  On success, a new algorithm ID is stored in
2187 @var{algorithm_id} and a pointer representhing this module is stored
2188 in @var{module}.
2189 @end deftypefun
2190
2191 @deftypefun void gcry_pk_unregister (gcry_module_t @var{module})
2192 Unregister the public key module identified by @var{module}, which
2193 must have been registered with gcry_pk_register.
2194 @end deftypefun
2195
2196 @deftypefun gcry_error_t gcry_pk_list (int *@var{list}, int *@var{list_length})
2197 Get a list consisting of the IDs of the loaded pubkey modules.  If
2198 @var{list} is zero, write the number of loaded pubkey modules to
2199 @var{list_length} and return.  If @var{list} is non-zero, the first
2200 *@var{list_length} algorithm IDs are stored in @var{list}, which must
2201 be of according size.  In case there are less pubkey modules than
2202 *@var{list_length}, *@var{list_length} is updated to the correct
2203 number.
2204 @end deftypefun
2205
2206 @node Cryptographic Functions
2207 @section Cryptographic Functions
2208
2209 @noindent
2210 Note, that we will in future allow to use keys without p,q and u
2211 specified and may also support other parameters for performance
2212 reasons. 
2213
2214 @noindent
2215
2216 Some functions operating on S-expressions support `flags', that
2217 influence the operation.  These flags have to be listed in a
2218 sub-S-expression named `flags'; the following flags are known:
2219
2220 @table @var
2221 @item pkcs1
2222 Use PKCS#1 block type 2 padding.
2223 @item no-blinding
2224 Do not use a technique called `blinding', which is used by default in
2225 order to prevent leaking of secret information.  Blinding is only
2226 implemented by RSA, but it might be implemented by other algorithms in
2227 the future as well, when necessary.
2228 @end table
2229
2230 @noindent
2231 Now that we know the key basics, we can carry on and explain how to
2232 encrypt and decrypt data.  In almost all cases the data is a random
2233 session key which is in turn used for the actual encryption of the real
2234 data.  There are 2 functions to do this:
2235
2236 @deftypefun gcry_error_t gcry_pk_encrypt (@w{gcry_sexp_t *@var{r_ciph},} @w{gcry_sexp_t @var{data},} @w{gcry_sexp_t @var{pkey}})
2237
2238 Obviously a public key must be provided for encryption.  It is
2239 expected as an appropriate S-expression (see above) in @var{pkey}.
2240 The data to be encrypted can either be in the simple old format, which
2241 is a very simple S-expression consisting only of one MPI, or it may be
2242 a more complex S-expression which also allows to specify flags for
2243 operation, like e.g. padding rules.
2244
2245 @noindent
2246 If you don't want to let @acronym{Libgcrypt} handle the padding, you must pass an
2247 appropriate MPI using this expression for @var{data}:
2248
2249 @example 
2250 (data
2251   (flags raw)
2252   (value @var{mpi}))
2253 @end example
2254
2255 @noindent
2256 This has the same semantics as the old style MPI only way.  @var{MPI} is
2257 the actual data, already padded appropriate for your protocol.  Most
2258 systems however use PKCS#1 padding and so you can use this S-expression
2259 for @var{data}:
2260
2261 @example 
2262 (data
2263   (flags pkcs1)
2264   (value @var{block}))
2265 @end example
2266
2267 @noindent
2268 Here, the "flags" list has the "pkcs1" flag which let the function know
2269 that it should provide PKCS#1 block type 2 padding.  The actual data to
2270 be encrypted is passed as a string of octets in @var{block}.  The
2271 function checks that this data actually can be used with the given key,
2272 does the padding and encrypts it.
2273
2274 If the function could successfully perform the encryption, the return
2275 value will be 0 and a a new S-expression with the encrypted result is
2276 allocated and assign to the variable at the address of @var{r_ciph}.
2277 The caller is responsible to release this value using
2278 @code{gcry_sexp_release}.  In case of an error, an error code is
2279 returned and @var{r_ciph} will be set to @code{NULL}.
2280
2281 @noindent
2282 The returned S-expression has this format when used with RSA:
2283
2284 @example
2285 (enc-val
2286   (rsa
2287     (a @var{a-mpi})))
2288 @end example
2289
2290 @noindent
2291 Where @var{a-mpi} is an MPI with the result of the RSA operation.  When
2292 using the ElGamal algorithm, the return value will have this format:
2293
2294 @example
2295 (enc-val
2296   (elg
2297     (a @var{a-mpi})
2298     (b @var{b-mpi})))
2299 @end example
2300
2301 @noindent
2302 Where @var{a-mpi} and @var{b-mpi} are MPIs with the result of the
2303 ElGamal encryption operation.
2304 @end deftypefun
2305 @c end gcry_pk_encrypt
2306
2307 @deftypefun gcry_error_t gcry_pk_decrypt (@w{gcry_sexp_t *@var{r_plain},} @w{gcry_sexp_t @var{data},} @w{gcry_sexp_t @var{skey}})
2308
2309 Obviously a private key must be provided for decryption.  It is expected
2310 as an appropriate S-expression (see above) in @var{skey}.  The data to
2311 be decrypted must match the format of the result as returned by
2312 @code{gcry_pk_encrypt}, but should be enlarged with a @code{flags}
2313 element:
2314
2315 @example
2316 (enc-val
2317   (flags)
2318   (elg
2319     (a @var{a-mpi})
2320     (b @var{b-mpi})))
2321 @end example
2322
2323 @noindent
2324 Note, that this function currently does not know of any padding
2325 methods and the caller must do any un-padding on his own.
2326
2327 @noindent
2328 The function returns 0 on success or an error code.  The variable at the
2329 address of @var{r_plain} will be set to NULL on error or receive the
2330 decrypted value on success.  The format of @var{r_plain} is a
2331 simple S-expression part (i.e. not a valid one) with just one MPI if
2332 there was no @code{flags} element in @var{data}; if at least an empty
2333 @code{flags} is passed in @var{data}, the format is:
2334
2335 @example
2336 (value @var{plaintext})
2337 @end example
2338 @end deftypefun
2339 @c end gcry_pk_decrypt
2340
2341
2342 Another operation commonly performed using public key cryptography is
2343 signing data.  In some sense this is even more important than
2344 encryption because digital signatures are an important instrument for
2345 key management.  @acronym{Libgcrypt} supports digital signatures using
2346 2 functions, similar to the encryption functions:
2347
2348 @deftypefun gcry_error_t gcry_pk_sign (@w{gcry_sexp_t *@var{r_sig},} @w{gcry_sexp_t @var{data},} @w{gcry_sexp_t @var{skey}})
2349
2350 This function creates a digital signature for @var{data} using the
2351 private key @var{skey} and place it into the variable at the address of
2352 @var{r_sig}.  @var{data} may either be the simple old style S-expression
2353 with just one MPI or a modern and more versatile S-expression which
2354 allows to let @acronym{Libgcrypt} handle padding:
2355
2356 @example 
2357  (data
2358   (flags pkcs1)
2359   (hash @var{hash-algo} @var{block}))
2360 @end example
2361
2362 @noindent
2363 This example requests to sign the data in @var{block} after applying
2364 PKCS#1 block type 1 style padding.  @var{hash-algo} is a string with the
2365 hash algorithm to be encoded into the signature, this may be any hash
2366 algorithm name as supported by @acronym{Libgcrypt}.  Most likely, this will be
2367 "sha1", "rmd160" or "md5".  It is obvious that the length of @var{block}
2368 must match the size of that message digests; the function checks that
2369 this and other constraints are valid.
2370
2371 @noindent
2372 If PKCS#1 padding is not required (because the caller does already
2373 provide a padded value), either the old format or better the following
2374 format should be used:
2375
2376 @example
2377 (data
2378   (flags raw)
2379   (value @var{mpi}))
2380 @end example
2381
2382 @noindent
2383 Here, the data to be signed is directly given as an @var{MPI}.
2384
2385 @noindent
2386 The signature is returned as a newly allocated S-expression in
2387 @var{r_sig} using this format for RSA:
2388
2389 @example
2390 (sig-val
2391   (rsa
2392     (s @var{s-mpi})))
2393 @end example
2394
2395 Where @var{s-mpi} is the result of the RSA sign operation.  For DSA the
2396 S-expression returned is:
2397
2398 @example
2399 (sig-val
2400   (dsa
2401     (r @var{r-mpi})
2402     (s @var{s-mpi})))
2403 @end example
2404
2405 Where @var{r-mpi} and @var{s-mpi} are the result of the DSA sign
2406 operation.  For ElGamal signing (which is slow, yields large numbers
2407 and probably is not as secure as the other algorithms), the same format is
2408 used with "elg" replacing "dsa".
2409 @end deftypefun
2410 @c end gcry_pk_sign
2411
2412 @noindent
2413 The operation most commonly used is definitely the verification of a
2414 signature.  @acronym{Libgcrypt} provides this function:
2415
2416 @deftypefun gcry_error_t gcry_pk_verify (@w{gcry_sexp_t @var{sig}}, @w{gcry_sexp_t @var{data}}, @w{gcry_sexp_t @var{pkey}})
2417
2418 This is used to check whether the signature @var{sig} matches the
2419 @var{data}.  The public key @var{pkey} must be provided to perform this
2420 verification.  This function is similar in its parameters to
2421 @code{gcry_pk_sign} with the exceptions that the public key is used
2422 instead of the private key and that no signature is created but a
2423 signature, in a format as created by @code{gcry_pk_sign}, is passed to
2424 the function in @var{sig}.
2425
2426 @noindent
2427 The result is 0 for success (i.e. the data matches the signature), or an
2428 error code where the most relevant code is @code{GCRYERR_BAD_SIGNATURE}
2429 to indicate that the signature does not match the provided data.
2430
2431 @end deftypefun
2432 @c end gcry_pk_verify
2433
2434 @node General public-key related Functions
2435 @section General public-key related Functions
2436
2437 @noindent
2438 A couple of utility functions are available to retrieve the length of
2439 the key, map algorithm identifiers and perform sanity checks:
2440
2441 @deftypefun {const char *} gcry_pk_algo_name (int @var{algo})
2442
2443 Map the public key algorithm id @var{algo} to a string representation of
2444 the algorithm name.  For unknown algorithms this functions returns an
2445 empty string.
2446 @end deftypefun
2447
2448 @deftypefun int gcry_pk_map_name (const char *@var{name})
2449
2450 Map the algorithm @var{name} to a public key algorithm Id.  Returns 0 if
2451 the algorithm name is not known.
2452 @end deftypefun
2453
2454 @deftypefun int gcry_pk_test_algo (int @var{algo})
2455
2456 Return 0 if the public key algorithm @var{algo} is available for use.
2457 Note, that this is implemented as a macro.
2458 @end deftypefun
2459
2460
2461 @deftypefun {unsigned int} gcry_pk_get_nbits (gcry_sexp_t @var{key})
2462
2463 Return what is commonly referred as the key length for the given
2464 public or private in @var{key}.
2465 @end deftypefun
2466
2467 @deftypefun {unsigned char *} gcry_pk_get_keygrip (@w{gcry_sexp_t @var{key}}, @w{unsigned char *@var{array}})
2468
2469 Return the so called "keygrip" which is the SHA-1 hash of the public key
2470 parameters expressed in a way depended on the algorithm.  @var{array}
2471 must either provide space for 20 bytes or @code{NULL;}. In the latter
2472 case a newly allocated array of that size is returned.  On success a
2473 pointer to the newly allocated space or to @var{array} is returned.
2474 @code{NULL} is returned to indicate an error which is most likely an unknown
2475 algorithm or one where a "keygrip" has not yet been defined.
2476 The function accepts public or secret keys in @var{key}.
2477 @end deftypefun
2478
2479 @deftypefun gcry_error_t gcry_pk_testkey (gcry_sexp_t @var{key})
2480
2481 Return zero if the private key @var{key} is `sane', an error code otherwise.
2482 Note, that it is not possible to chek the `saneness' of a public key.
2483
2484 @end deftypefun
2485
2486
2487 @deftypefun int gcry_pk_algo_info (@w{int @var{algo}}, @w{int @var{what}}, @w{void *@var{buffer}}, @w{size_t *@var{nbytes}})
2488
2489 Depending on the value of @var{what} return various information about
2490 the public key algorithm with the id @var{algo}.  Note, that the
2491 function returns @code{-1} on error and the actual error code must be
2492 retrieved using the function @code{gcry_errno}.  The currently defined
2493 values for @var{what} are:
2494
2495 @table @code
2496 @item GCRYCTL_TEST_ALGO:
2497 Return 0 when the specified algorithm is available for use.
2498 @var{buffer} must be @code{NULL}, @var{nbytes} may be passed as
2499 @code{NULL} or point to a variable with the required usage of the
2500 algorithm. This may be 0 for "don't care" or the bit-wise OR of these
2501 flags:
2502
2503 @table @code
2504 @item GCRY_PK_USAGE_SIGN 
2505 Algorithm is usable for signing.
2506 @item GCRY_PK_USAGE_ENCR 
2507 Algorithm is usable for encryption.
2508 @end table
2509
2510 @item GCRYCTL_GET_ALGO_USAGE:
2511 Return the usage flags for the given algorithm.  An invalid algorithm
2512 return 0.  Disabled algorithms are ignored here because we
2513 want to know whether the algorithm is at all capable of a certain usage.
2514
2515 @item GCRYCTL_GET_ALGO_NPKEY
2516 Return the number of elements the public key for algorithm @var{algo}
2517 consist of.  Return 0 for an unknown algorithm.
2518
2519 @item GCRYCTL_GET_ALGO_NSKEY
2520 Return the number of elements the private key for algorithm @var{algo}
2521 consist of.  Note that this value is always larger than that of the
2522 public key.  Return 0 for an unknown algorithm.
2523
2524 @item GCRYCTL_GET_ALGO_NSIGN
2525 Return the number of elements a signature created with the algorithm
2526 @var{algo} consists of.  Return 0 for an unknown algorithm or for an
2527 algorithm not capable of creating signatures.
2528
2529 @item GCRYCTL_GET_ALGO_NENC
2530 Return the number of elements a encrypted message created with the algorithm
2531 @var{algo} consists of.  Return 0 for an unknown algorithm or for an
2532 algorithm not capable of encryption.
2533 @end table
2534
2535 @noindent
2536 Please note that parameters not required should be passed as @code{NULL}.
2537 @end deftypefun
2538 @c end gcry_pk_algo_info
2539
2540
2541 @deftypefun gcry_error_t gcry_pk_ctl (@w{int @var{cmd}}, @w{void *@var{buffer}}, @w{size_t @var{buflen}})
2542
2543 This is a general purpose function to perform certain control
2544 operations.  @var{cmd} controls what is to be done. The return value is
2545 0 for success or an error code.  Currently supported values for
2546 @var{cmd} are:
2547
2548 @table @code
2549 @item GCRYCTL_DISABLE_ALGO
2550 Disable the algorithm given as an algorithm id in @var{buffer}.
2551 @var{buffer} must point to an @code{int} variable with the algorithm id
2552 and @var{buflen} must have the value @code{sizeof (int)}.
2553
2554 @end table
2555 @end deftypefun
2556 @c end gcry_pk_ctl
2557
2558 @noindent
2559 @acronym{Libgcrypt} also provides a function for generating public key
2560 pairs:
2561
2562 @deftypefun gcry_error_t gcry_pk_genkey (@w{gcry_sexp_t *@var{r_key}}, @w{gcry_sexp_t @var{parms}})
2563
2564 This function create a new public key pair using information given in
2565 the S-expression @var{parms} and stores the private and the public key
2566 in one new S-expression at the address given by @var{r_key}.  In case of
2567 an error, @var{r_key} is set to @code{NULL}.  The return code is 0 for
2568 success or an error code otherwise.
2569
2570 @noindent
2571 Here is an example for @var{parms} for creating a 1024 bit RSA key:
2572
2573 @example
2574 (genkey
2575   (rsa
2576     (nbits 4:1024)))
2577 @end example
2578
2579 @noindent
2580 To create an ElGamal key, substitute "elg" for "rsa" and to create a DSA
2581 key use "dsa".  Valid ranges for the key length depend on the
2582 algorithms; all commonly used key lengths are supported.  Currently
2583 supported parameters are:
2584
2585 @table @code
2586 @item nbits
2587 This is always required to specify the length of the key.  The argument
2588 is a string with a number in C-notation.
2589
2590 @item rsa-use-e
2591 This is only used with RSA to give a hint for the public exponent. The
2592 value will be used as a base to test for a usable exponent. Some values
2593 are special:
2594
2595 @table @samp
2596 @item 0
2597 Use a secure and fast value.  This is currently the number 41.
2598 @item 1
2599 Use a secure value as required by some specification.  This is currently
2600 the number 65537.
2601 @item 2
2602 Reserved
2603 @end table
2604
2605 @noindent
2606 If this parameter is not used, @acronym{Libgcrypt} uses for historic reasons
2607 65537.
2608
2609 @end table
2610 @c end table of parameters
2611
2612 @noindent
2613 The key pair is returned in a format depending on the algorithm.  Both
2614 private and public keys are returned in one container and may be
2615 accompanied by some miscellaneous information.
2616
2617 @noindent
2618 As an example, here is what the ElGamal key generation returns:
2619
2620 @example
2621 (key-data
2622   (public-key
2623     (elg
2624       (p @var{p-mpi})
2625       (g @var{g-mpi})
2626       (y @var{y-mpi})))
2627   (private-key
2628     (elg
2629       (p @var{p-mpi})
2630       (g @var{g-mpi})
2631       (y @var{y-mpi})
2632       (x @var{x-mpi})))
2633   (misc-key-info
2634     (pm1-factors @var{n1 n2 ... nn})))
2635 @end example
2636
2637 @noindent
2638 As you can see, some of the information is duplicated, but this provides
2639 an easy way to extract either the public or the private key.  Note that
2640 the order of the elements is not defined, e.g. the private key may be
2641 stored before the public key. @var{n1 n2 ... nn} is a list of prime
2642 numbers used to composite @var{p-mpi}; this is in general not a very
2643 useful information.
2644 @end deftypefun
2645 @c end gcry_pk_genkey
2646
2647 @node Public Key cryptography (II)
2648 @chapter Public Key cryptography (II)
2649
2650 This chapter documents the alternative interface to asymmetric
2651 cryptography (ac) that is not based on S-expressions, but on native C
2652 data structures.  As opposed to the pk interface described in the
2653 former chapter, this one follows an open/use/close paradigm like other
2654 building blocks of the library.
2655
2656 @menu
2657 * Available asymmetric algorithms::  List of algorithms supported by the library.
2658 * Working with sets of data::   How to work with sets of data.
2659 * Working with handles::        How to use handles.
2660 * Working with keys::           How to work with keys.
2661 * Using cryptographic functions::  How to perform cryptographic operations.
2662 * Handle-independent functions::  General functions independent of handles.
2663 @end menu
2664
2665 @node Available asymmetric algorithms
2666 @section Available asymmetric algorithms
2667
2668 @acronym{Libgcrypt} supports the RSA (Rivest-Shamir-Adleman)
2669 algorithms as well as DSA (Digital Signature Algorithm) and ElGamal.
2670 The versatile interface allows to add more algorithms in the future.
2671
2672 @deftp {Data type} gcry_ac_id_t
2673
2674 The following constants are defined for this type:
2675
2676 @table @code
2677 @item GCRY_AC_RSA
2678 Riven-Shamir-Adleman
2679 @item GCRY_AC_DSA
2680 Digital Signature Algorithm
2681 @item GCRY_AC_ELG
2682 ElGamal
2683 @item GCRY_AC_ELG_E
2684 ElGamal, encryption only.
2685 @end table
2686 @end deftp
2687
2688 @node Working with sets of data
2689 @section Working with sets of data
2690
2691 In the context of this interface the term `data set' refers to a list
2692 of `named MPI values' that is used by functions performing
2693 cryptographic operations.
2694
2695 Such data sets are used for representing keys, since keys simply
2696 consist of a variable amount of numbers.  Furthermore some functions
2697 return data sets to the caller that are to be provided to other
2698 functions.
2699
2700 This section documents the data types, symbols and functions that are
2701 relevant for working with such data sets.
2702
2703 @deftp {Data type} gcry_ac_data_t
2704 A data set, that is simply a list of named MPI values.
2705 @end deftp
2706
2707 The following flags are supported:
2708
2709 @table @code
2710 @item GCRY_AC_FLAG_DEALLOC
2711 Used for storing data in a data set.  If given, the data will be
2712 released by the library.
2713
2714 @item GCRY_AC_FLAG_COPY
2715 Used for storing/retrieving data in/from a data set.  If given, the
2716 library will create copies of the provided/contained data, which will
2717 then be given to the user/associated with the data set.
2718 @end table
2719
2720 @deftypefun gcry_error_t gcry_ac_data_new (gcry_ac_data_t *@var{data})
2721 Creates a new, empty data set and stores it in @var{data}.
2722 @end deftypefun
2723
2724 @deftypefun void gcry_ac_data_destroy (gcry_ac_data_t @var{data})
2725 Destroys the data set @var{data}.
2726 @end deftypefun
2727
2728 @deftypefun gcry_error_t gcry_ac_data_set (gcry_ac_data_t @var{data},
2729 unsigned int @var{flags}, char *@var{name}, gcry_mpi_t @var{mpi})
2730 Add the value @var{mpi} to @var{data} with the label @var{name}.  If
2731 @var{flags} contains GCRY_AC_FLAG_DATA_COPY, the data set will contain
2732 copies of @var{name} and @var{mpi}.  If @var{flags} contains
2733 GCRY_AC_FLAG_DATA_DEALLOC or GCRY_AC_FLAG_DATA_COPY, the values
2734 contained in the data set will be deallocated when they are to be
2735 removed from the data set.
2736 @end deftypefun
2737
2738 @deftypefun gcry_error_t gcry_ac_data_copy (gcry_ac_data_t *@var{data_cp}, gcry_ac_data_t @var{data})
2739 Create a copy of the data set @var{data} and store it in @var{data_cp}.
2740 @end deftypefun
2741
2742 @deftypefun unsigned int gcry_ac_data_length (gcry_ac_data_t @var{data})
2743 Returns the number of named MPI values inside of the data set
2744 @var{data}.
2745 @end deftypefun
2746
2747 @deftypefun gcry_error_t gcry_ac_data_get_name (gcry_ac_data_t @var{data},
2748 unsigned int @var{flags}, char *@var{name}, gcry_mpi_t *@var{mpi})
2749 Store the value labelled with @var{name} found in @var{data} in
2750 @var{mpi}.  If @var{flags} contains GCRY_AC_FLAG_COPY, store a copy of
2751 the @var{mpi} value contained in the data set.  @var{mpi} may be NULL.
2752 @end deftypefun
2753
2754 @deftypefun gcry_error_t gcry_ac_data_get_index (gcry_ac_data_t @var{data},
2755 unsigned int flags, unsigned int @var{index},
2756 const char **@var{name}, gcry_mpi_t *@var{mpi})
2757 Stores in @var{name} and @var{mpi} the named @var{mpi} value contained
2758 in the data set @var{data} with the index @var{idx}.  If @var{flags}
2759 contains GCRY_AC_FLAG_COPY, store copies of the values contained in
2760 the data set. @var{name} or @var{mpi} may be NULL.
2761 @end deftypefun
2762
2763 @deftypefun void gcry_ac_data_clear (gcry_ac_data_t @var{data})
2764 Destroys any values contained in the data set @var{data}.
2765 @end deftypefun
2766
2767 @node Working with handles
2768 @section Working with handles
2769
2770 In order to use an algorithm, an according handle must be created.
2771 This is done using the following function:
2772
2773 @deftypefun gcry_error_t gcry_ac_open (gcry_ac_handle_t *@var{handle},
2774 int @var{algorithm}, int @var{flags})
2775
2776 Creates a new handle for the algorithm @var{algorithm} and stores it
2777 in @var{handle}.  @var{flags} is not used yet.
2778
2779 @var{algorithm} must be a valid algorithm ID, see @xref{Available
2780 algorithms}, for a list of supported algorithms and the according
2781 constants.  Besides using the listed constants directly, the functions
2782 @code{gcry_ac_name_to_id} may be used to convert the textual name of
2783 an algorithm into the according numeric ID.
2784 @end deftypefun
2785
2786 @deftypefun void gcry_ac_close (gcry_ac_handle_t @var{handle})
2787 Destroys the handle @var{handle}.
2788 @end deftypefun
2789
2790 @node Working with keys
2791 @section Working with keys
2792
2793 @deftp {Data type} gcry_ac_key_type_t
2794 Defined constants:
2795
2796 @table @code
2797 @item GCRY_AC_KEY_TYPE_SECRET
2798 Specifies a secret key.
2799 @item GCRY_AC_KEY_TYPE_PUBLIC
2800 Specifies a public key.
2801 @end table
2802 @end deftp
2803
2804 @deftp {Data type} gcry_ac_key_t
2805 This type represents a single `key', either a secret one or a public
2806 one.
2807 @end deftp
2808
2809 @deftp {Data type} gcry_ac_key_pair_t
2810 This type represents a `key pair' containing a secret and a public key.
2811 @end deftp
2812
2813 Key data structures can be created in two different ways; a new key
2814 pair can be generated, resulting in ready-to-use key.  Alternatively a
2815 key can be initialized from a given data set.
2816
2817 @deftypefun gcry_error_t gcry_ac_key_init (gcry_ac_key_t *@var{key}, gcry_ac_handle_t @var{handle}, gcry_ac_key_type_t @var{type}, gcry_ac_data_t @var{data})
2818 Creates a new key of type @var{type}, consisting of the MPI values
2819 contained in the data set @var{data} and stores it in @var{key}.
2820 @end deftypefun
2821
2822 @deftypefun gcry_error_t gcry_ac_key_pair_generate (gcry_ac_handle_t @var{handle},
2823 unsigned int @var{nbits}, void *@var{key_spec}, gcry_ac_key_pair_t *@var{key_pair},
2824 gcry_mpi_t **@var{misc_data})
2825
2826 Generates a new key pair via the handle @var{handle} of @var{NBITS}
2827 bits and stores it in @var{key_pair}.
2828
2829 In case non-standard settings are wanted, a pointer to a structure of
2830 type @code{gcry_ac_key_spec_<algorithm>_t}, matching the selected
2831 algorithm, can be given as @var{key_spec}.  @var{misc_data} is not
2832 used yet.  Such a structure does only exist for RSA.  A descriptions
2833 of the members of the supported structures follows.
2834
2835 @table @code
2836 @item gcry_ac_key_spec_rsa_t
2837 @table @code
2838 @item gcry_mpi_t e
2839 Generate the key pair using a special @code{e}.  The value of @code{e}
2840 has the following meanings:
2841 @table @code
2842 @item = 0
2843 Let @acronym{Libgcrypt} device what exponent should be used.
2844 @item = 1
2845 Request the use of a ``secure'' exponent; this is required by some
2846 specification to be 65537.
2847 @item > 2
2848 Try starting at this value until a working exponent is found.  Note,
2849 that the current implementation leaks some information about the
2850 private key because the incrementation used is not randomized.  Thus,
2851 this function will be changed in the future to return a random
2852 exponent of the given size.
2853 @end table
2854 @end table
2855 @end table
2856
2857 Example code:
2858 @example
2859 @{
2860   gcry_ac_key_pair_t key_pair;
2861   gcry_ac_key_spec_rsa  rsa_spec;
2862
2863   rsa_spec.e = gcry_mpi_new (0);
2864   gcry_mpi_set_ui (rsa_spec.e, 1)
2865
2866   err = gcry_ac_open  (&handle, GCRY_AC_RSA, 0);
2867   assert (! err);
2868
2869   err = gcry_ac_key_pair_generate (handle, &key_pair, 1024, (void *) &rsa_spec);
2870   assert (! err);
2871 @}
2872 @end example
2873 @end deftypefun
2874
2875
2876 @deftypefun gcry_ac_key_t gcry_ac_key_pair_extract (gcry_ac_key_pair_t @var{key_pair}, gcry_ac_key_type_t @var{which})
2877 Returns the key of type @var{which} out of the key pair
2878 @var{key_pair}.
2879 @end deftypefun
2880
2881 @deftypefun void gcry_ac_key_destroy (gcry_ac_key_t @var{key})
2882 Destroys the key @var{key}.
2883 @end deftypefun
2884
2885 @deftypefun void gcry_ac_key_pair_destroy (gcry_ac_key_pair_t @var{key_pair})
2886 Destroys the key pair @var{key_pair}.
2887 @end deftypefun
2888
2889 @deftypefun gcry_ac_data_t gcry_ac_key_data_get (gcry_ac_key_t @var{key})
2890 Returns the data set contained in the key @var{key}.
2891 @end deftypefun
2892
2893 @deftypefun gcry_error_t gcry_ac_key_test (gcry_ac_handle_t @var{handle}, gcry_ac_key_t @var{key})
2894 Verifies that the private key @var{key} is sane via @var{handle}.
2895 @end deftypefun
2896
2897 @deftypefun gcry_error_t gcry_ac_key_get_nbits (gcry_ac_handle_t @var{handle},
2898 gcry_ac_key_t @var{key}, unsigned int *@var{nbits})
2899 Stores the number of bits of the key @var{key} in @var{nbits} via @var{handle}.
2900 @end deftypefun
2901
2902 @deftypefun gcry_error_t gcry_ac_key_get_grip (gcry_ac_handle_t @var{handle},
2903 gcry_ac_key_t @var{key}, unsigned char *@var{key_grip})
2904 Writes the 20 byte long key grip of the key @var{key} to
2905 @var{key_grip} via @var{handle}.
2906 @end deftypefun
2907
2908 @node Using cryptographic functions
2909 @section Using cryptographic functions
2910
2911 The following flags might be relevant:
2912
2913 @table @code
2914 @item GCRY_AC_FLAG_NO_BLINDING
2915 Disable any blinding, which might be supported by the chosen
2916 algorithm; blinding is the default.
2917 @end table
2918
2919 @deftypefun gcry_error_t gcry_ac_data_encrypt (gcry_ac_handle_t @var{handle}, unsigned int @var{flags}, gcry_ac_key_t @var{key}, gcry_mpi_t @var{data_plain}, gcry_ac_data_t **@var{data_encrypted})
2920 Encrypts the plain text MPI value @var{data_plain} with the key public
2921 @var{key} under the control of the flags @var{flags} and stores the
2922 resulting data set into @var{data_encrypted}.
2923 @end deftypefun
2924
2925 @deftypefun gcry_error_t gcry_ac_data_decrypt (gcry_ac_handle_t @var{handle}, unsigned int @var{flags}, gcry_ac_key_t @var{key}, gcry_mpi_t *@var{data_plain}, gcry_ac_data_t @var{data_encrypted})
2926 Decrypts the encrypted data contained in the data set
2927 @var{data_encrypted} with the secret key KEY under the control of the
2928 flags @var{flags} and stores the resulting plain text MPI value in
2929 @var{DATA_PLAIN}.
2930 @end deftypefun
2931
2932 @deftypefun gcry_error_t gcry_ac_data_sign (gcry_ac_handle_t @var{handle}, gcry_ac_key_t @var{key}, gcry_mpi_t @var{data}, gcry_ac_data_t *@var{data_signature})
2933 Signs the data contained in @var{data} with the secret key @var{key}
2934 and stores the resulting signature in the data set
2935 @var{data_signature}.
2936 @end deftypefun
2937
2938 @deftypefun gcry_error_t gcry_ac_data_verify (gcry_ac_handle_t @var{handle}, gcry_ac_key_t @var{key}, gcry_mpi_t @var{data}, gcry_ac_data_t @var{data_signature})
2939 Verifies that the signature contained in the data set
2940 @var{data_signature} is indeed the result of signing the data
2941 contained in @var{data} with the secret key belonging to the public
2942 key @var{key}.
2943 @end deftypefun
2944
2945 @node Handle-independent functions
2946 @section Handle-independent functions
2947
2948 @deftypefun gcry_error_t gcry_ac_id_to_name (gcry_ac_id_t @var{algorithm}, const char **@var{name})
2949 Stores the textual representation of the algorithm whose id is given
2950 in @var{algorithm} in @var{name}.
2951 @end deftypefun
2952
2953 @deftypefun gcry_error_t gcry_ac_name_to_id (const char *@var{name}, gcry_ac_id_t *@var{algorithm})
2954 Stores the numeric ID of the algorithm whose textual representation is
2955 contained in @var{name} in @var{algorithm}.
2956 @end deftypefun
2957
2958 @c **********************************************************
2959 @c *******************  Random  *****************************
2960 @c **********************************************************
2961 @node Random Numbers
2962 @chapter Random Numbers
2963
2964 @menu
2965 * Quality of random numbers::   @acronym{Libgcrypt} uses different quality levels.
2966 * Retrieving random numbers::   How to retrieve random numbers.
2967 @end menu
2968
2969 @node Quality of random numbers
2970 @section Quality of random numbers
2971
2972 @acronym{Libgcypt} offers random numbers of different quality levels:
2973
2974 @deftp {Data type} enum gcry_random_level
2975 The constants for the random quality levels are of this type.
2976 @end deftp
2977
2978 @table @code
2979 @item GCRY_WEAK_RANDOM
2980 This should not anymore be used.  It has recently been changed to an
2981 alias of GCRY_STRONG_RANDOM.  Use @code{gcry_create_nonce} instead.
2982 @item GCRY_STRONG_RANDOM
2983 Use this level for e.g. session keys and similar purposes.
2984 @item GCRY_VERY_STRONG_RANDOM
2985 Use this level for e.g. key material.
2986 @end table
2987
2988 @node Retrieving random numbers
2989 @section Retrieving random numbers
2990
2991 @deftypefun void gcry_randomize (unsigned char *@var{buffer}, size_t @var{length}, enum gcry_random_level @var{level})
2992
2993 Fill @var{buffer} with @var{length} random bytes using a random quality
2994 as defined by @var{level}.
2995 @end deftypefun
2996
2997 @deftypefun void * gcry_random_bytes (size_t @var{nbytes}, enum gcry_random_level @var{level})
2998
2999 Allocate a memory block consisting of @var{nbytes} fresh random bytes
3000 using a random quality as defined by @var{level}.
3001 @end deftypefun
3002
3003 @deftypefun void * gcry_random_bytes_secure (size_t @var{nbytes}, enum gcry_random_level @var{level})
3004
3005 Allocate a memory block consisting of @var{nbytes} fresh random bytes
3006 using a random quality as defined by @var{level}.  This function
3007 differs from @code{gcry_random_bytes} in that the returned buffer is
3008 allocated in a ``secure'' area of the memory.
3009 @end deftypefun
3010
3011 @deftypefun void gcry_create_nonce (unsigned char *@var{buffer}, size_t @var{length})
3012
3013 Fill @var{buffer} with @var{length} unpredictable bytes.  This is
3014 commonly called a nonce and may also be used for initialization
3015 vectors and padding.  This is an extra function nearly independent of
3016 the other random function for 3 reasons: It better protects the
3017 regular random generator's internal state, provides better performance
3018 and does not drain the precious entropy pool.
3019
3020 @end deftypefun
3021
3022
3023
3024 @c **********************************************************
3025 @c *******************  S-Expressions ***********************
3026 @c **********************************************************
3027 @node S-expressions
3028 @chapter S-expressions
3029
3030 S-expressions are used by the public key functions to pass complex data
3031 structures around.  These LISP like objects are used by some
3032 cryptographic protocols (cf. RFC-2692) and @acronym{Libgcrypt} provides functions
3033 to parse and construct them.  For detailed information, see
3034 @cite{Ron Rivest, code and description of S-expressions,
3035 @uref{http://theory.lcs.mit.edu/~rivest/sexp.html}}.
3036
3037 @menu
3038 * Data types for S-expressions::  Data types related with S-expressions.
3039 * Working with S-expressions::  How to work with S-expressions.
3040 @end menu
3041
3042 @node Data types for S-expressions
3043 @section Data types for S-expressions
3044
3045 @deftp {Data type} gcry_sexp_t
3046 The @code{gcry_sexp_t} type describes an object with the @acronym{Libgcrypt} internal
3047 representation of an S-expression.
3048 @end deftp
3049
3050 @node Working with S-expressions
3051 @section Working with S-expressions
3052
3053 @noindent
3054 There are several functions to create an @acronym{Libgcrypt} S-expression object
3055 from its external representation or from a string template.  There is
3056 also a function to convert the internal representation back into one of
3057 the external formats:
3058
3059
3060 @deftypefun gcry_error_t gcry_sexp_new (@w{gcry_sexp_t *@var{r_sexp}}, @w{const void *@var{buffer}}, @w{size_t @var{length}}, @w{int @var{autodetect}})
3061
3062 This is the generic function to create an new S-expression object from
3063 its external representation in @var{buffer} of @var{length} bytes.  On
3064 success the result is stored at the address given by @var{r_sexp}. 
3065 With @var{autodetect} set to 0, the data in @var{buffer} is expected to
3066 be in canonized format, with @var{autodetect} set to 1 the parses any of
3067 the defined external formats.  If @var{buffer} does not hold a valid
3068 S-expression an error code is returned and @var{r_sexp} set to
3069 @code{NULL}.
3070 Note, that the caller is responsible for releasing the newly allocated
3071 S-expression using @code{gcry_sexp_release}.
3072 @end deftypefun
3073
3074 @deftypefun gcry_error_t gcry_sexp_create (@w{gcry_sexp_t *@var{r_sexp}}, @w{void *@var{buffer}}, @w{size_t @var{length}}, @w{int @var{autodetect}}, @w{void (*@var{freefnc})(void*)})
3075
3076 This function is identical to @code{gcry_sexp_new} but has an extra
3077 argument @var{freefnc}, which, when not set to @code{NULL}, is expected
3078 to be a function to release the @var{buffer}; most likely the standard
3079 @code{free} function is used for this argument.  This has the effect of
3080 transferring the ownership of @var{buffer} to the created object in
3081 @var{r_sexp}.  The advantage of using this function is that @acronym{Libgcrypt}
3082 might decide to directly use the provided buffer and thus avoid extra
3083 copying.
3084 @end deftypefun
3085
3086 @deftypefun gcry_error_t gcry_sexp_sscan (@w{gcry_sexp_t *@var{r_sexp}}, @w{size_t *@var{erroff}}, @w{const char *@var{buffer}}, @w{size_t @var{length}})
3087
3088 This is another variant of the above functions.  It behaves nearly
3089 identical but provides an @var{erroff} argument which will receive the
3090 offset into the buffer where the parsing stopped on error.
3091 @end deftypefun
3092
3093 @deftypefun gcry_error_t gcry_sexp_build (@w{gcry_sexp_t *@var{r_sexp}}, @w{size_t *@var{erroff}}, @w{const char *@var{format}, ...})
3094
3095 This function creates an internal S-expression from the string template
3096 @var{format} and stores it at the address of @var{r_sexp}. If there is a
3097 parsing error, the function returns an appropriate error code and stores
3098 the offset into @var{format} where the parsing stopped in @var{erroff}.
3099 The function supports a couple of printf-like formatting characters and
3100 expects arguments for some of these escape sequences right after
3101 @var{format}.  The following format characters are defined:
3102
3103 @table @samp
3104 @item %m
3105 The next argument is expected to be of type @code{gcry_mpi_t} and a copy of
3106 its value is inserted into the resulting S-expression.
3107 @item %s
3108 The next argument is expected to be of type @code{char *} and that
3109 string is inserted into the resulting S-expression.
3110 @item %d
3111 The next argument is expected to be of type @code{int} and its 
3112 value ist inserted into the resulting S-expression.
3113 @item %b
3114 The next argument is expected to be of type @code{int} directly
3115 followed by an argument of type @code{char *}.  This represents a
3116 buffer of given length to be inserted into the resulting regular
3117 expression.
3118 @end table
3119
3120 @noindent
3121 No other format characters are defined and would return an error.  Note,
3122 that the format character @samp{%%} does not exists, because a percent
3123 sign is not a valid character in an S-expression.
3124 @end deftypefun
3125
3126 @deftypefun void gcry_sexp_release (@w{gcry_sexp_t @var{sexp}})
3127
3128 Release the S-expression object @var{sexp}.
3129 @end deftypefun
3130
3131
3132 @noindent
3133 The next 2 functions are used to convert the internal representation
3134 back into a regular external S-expression format and to show the
3135 structure for debugging.
3136
3137 @deftypefun size_t gcry_sexp_sprint (@w{gcry_sexp_t @var{sexp}}, @w{int @var{mode}}, @w{char *@var{buffer}}, @w{size_t @var{maxlength}})
3138
3139 Copies the S-expression object @var{sexp} into @var{buffer} using the
3140 format specified in @var{mode}.  @var{maxlength} must be set to the
3141 allocated length of @var{buffer}.  The function returns the actual
3142 length of valid bytes put into @var{buffer} or 0 if the provided buffer
3143 is too short.  Passing @code{NULL} for @var{buffer} returns the required
3144 length for @var{buffer}.  For convenience reasons an extra byte with
3145 value 0 is appended to the buffer.
3146
3147 @noindent
3148 The following formats are supported:
3149
3150 @table @code
3151 @item GCRYSEXP_FMT_DEFAULT
3152 Returns a convenient external S-expression representation.
3153
3154 @item GCRYSEXP_FMT_CANON
3155 Return the S-expression in canonical format.
3156
3157 @item GCRYSEXP_FMT_BASE64
3158 Not currently supported.
3159
3160 @item GCRYSEXP_FMT_ADVANCED
3161 Returns the S-expression in advanced format.
3162 @end table
3163 @end deftypefun
3164
3165 @deftypefun void gcry_sexp_dump (@w{gcry_sexp_t @var{sexp}})
3166
3167 Dumps @var{sexp} in a format suitable for debugging to @acronym{Libgcrypt}'s
3168 logging stream.
3169 @end deftypefun
3170
3171 @noindent
3172 Often canonical encoding is used in the external representation.  The
3173 following function can be used to check for valid encoding and to learn
3174 the length of the S-expression"
3175
3176 @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}})
3177
3178 Scan the canonical encoded @var{buffer} with implicit length values and
3179 return the actual length this S-expression uses.  For a valid S-expression
3180 it should never return 0.  If @var{length} is not 0, the maximum
3181 length to scan is given; this can be used for syntax checks of
3182 data passed from outside.  @var{errcode} and @var{erroff} may both be
3183 passed as @code{NULL}.
3184
3185 @end deftypefun
3186
3187
3188 @noindent
3189 There are a couple of functions to parse S-expressions and retrieve
3190 elements:
3191
3192 @deftypefun gcry_sexp_t gcry_sexp_find_token (@w{const gcry_sexp_t @var{list}}, @w{const char *@var{token}}, @w{size_t @var{toklen}})
3193
3194 Scan the S-expression for a sublist with a type (the car of the list)
3195 matching the string @var{token}.  If @var{toklen} is not 0, the token is
3196 assumed to be raw memory of this length.  The function returns a newly
3197 allocated S-expression consisting of the found sublist or @code{NULL}
3198 when not found.
3199 @end deftypefun
3200
3201
3202 @deftypefun int gcry_sexp_length (@w{const gcry_sexp_t @var{list}})
3203
3204 Return the length of the @var{list}.  For a valid S-expression this
3205 should be at least 1.
3206 @end deftypefun
3207
3208
3209 @deftypefun gcry_sexp_t gcry_sexp_nth (@w{const gcry_sexp_t @var{list}}, @w{int @var{number}})
3210
3211 Create and return a new S-expression from the element with index @var{number} in
3212 @var{list}.  Note that the first element has the index 0.  If there is
3213 no such element, @code{NULL} is returned.
3214 @end deftypefun
3215
3216 @deftypefun gcry_sexp_t gcry_sexp_car (@w{const gcry_sexp_t @var{list}})
3217
3218 Create and return a new S-expression from the first element in
3219 @var{list}; this called the "type" and should always exist and be a
3220 string. @code{NULL} is returned in case of a problem.
3221 @end deftypefun
3222
3223 @deftypefun gcry_sexp_t gcry_sexp_cdr (@w{const gcry_sexp_t @var{list}})
3224
3225 Create and return a new list form all elements except for the first one.
3226 Note, that this function may return an invalid S-expression because it
3227 is not guaranteed, that the type exists and is a string.  However, for
3228 parsing a complex S-expression it might be useful for intermediate
3229 lists.  Returns @code{NULL} on error.
3230 @end deftypefun
3231
3232
3233 @deftypefun {const char *} gcry_sexp_nth_data (@w{const gcry_sexp_t @var{list}}, @w{int @var{number}}, @w{size_t *@var{datalen}})
3234
3235 This function is used to get data from a @var{list}.  A pointer to the
3236 actual data with index @var{number} is returned and the length of this
3237 data will be stored to @var{datalen}.  If there is no data at the given
3238 index or the index represents another list, @code{NULL} is returned.
3239 @strong{Note:} The returned pointer is valid as long as @var{list} is
3240 not modified or released.
3241
3242 @noindent
3243 Here is an example on how to extract and print the surname (Meier) from
3244 the S-expression @samp{(Name Otto Meier (address Burgplatz 3))}:
3245
3246 @example
3247 size_t len;
3248 const char *name;
3249
3250 name = gcry_sexp_nth_data (list, 2, &len);
3251 printf ("my name is %.*s\n", (int)len, name);
3252 @end example
3253 @end deftypefun
3254
3255 @deftypefun gcry_mpi_t gcry_sexp_nth_mpi (@w{gcry_sexp_t @var{list}}, @w{int @var{number}}, @w{int @var{mpifmt}})
3256
3257 This function is used to get and convert data from a @var{list}. This
3258 data is assumed to be an MPI stored in the format described by
3259 @var{mpifmt} and returned as a standard @acronym{Libgcrypt} MPI.  The caller must
3260 release this returned value using @code{gcry_mpi_release}.  If there is
3261 no data at the given index, the index represents a list or the value
3262 can't be converted to an MPI, @code{NULL} is returned.
3263 @end deftypefun
3264
3265
3266 @c **********************************************************
3267 @c *******************  MPIs ******** ***********************
3268 @c **********************************************************
3269 @node MPI library
3270 @chapter MPI library
3271
3272 @menu
3273 * Data types::                  MPI related data types.
3274 * Basic functions::             First steps with MPI numbers.
3275 * MPI formats::                 External representation of MPIs.
3276 * Calculations::                Performing MPI calculations.
3277 * Comparisons::                 How to compare MPI values.
3278 * Bit manipulations::           How to access single bits of MPI values.
3279 * Misc::                        Misc, fixme.
3280 @end menu
3281
3282 Public key cryptography is based on mathematics with large numbers.  To
3283 implement the public key functions, a library for handling these large
3284 numbers is required.  Because of the general usefulness of such a
3285 library, its interface is exposed by @acronym{Libgcrypt}.  The implementation is
3286 based on an old release of GNU Multi-Precision Library (GMP) but in the
3287 meantime heavily modified and stripped down to what is required for
3288 cryptography. For a lot of CPUs, high performance assembler
3289 implementations of some very low level functions are used to gain much
3290 better performance than with the standard C implementation.
3291
3292 @noindent
3293 In the context of @acronym{Libgcrypt} and in most other applications, these large
3294 numbers are called MPIs (multi-precision-integers).
3295
3296 @node Data types
3297 @section Data types
3298
3299 @deftp {Data type} gcry_mpi_t
3300 The @code{gcry_mpi_t} type represents an object to hold an MPI.
3301 @end deftp
3302
3303 @node Basic functions
3304 @section Basic functions
3305
3306 @noindent
3307 To work with MPIs, storage must be allocated and released for the
3308 numbers.  This can be done with one of these functions:
3309
3310 @deftypefun gcry_mpi_t gcry_mpi_new (@w{unsigned int @var{nbits}})
3311
3312 Allocate a new MPI object, initialize it to 0 and initially allocate
3313 enough memory for a number of at least @var{nbits}.  This pre-allocation is
3314 only a small performance issue and not actually necessary because
3315 @acronym{Libgcrypt} automatically re-allocates the required memory.
3316 @end deftypefun
3317
3318 @deftypefun gcry_mpi_t gcry_mpi_snew (@w{unsigned int @var{nbits}})
3319
3320 This is identical to @code{gcry_mpi_new} but allocates the MPI in the so
3321 called "secure memory" which in turn will take care that all derived
3322 values will also be stored in this "secure memory".  Use this for highly
3323 confidential data like private key parameters.
3324 @end deftypefun
3325
3326 @deftypefun gcry_mpi_t gcry_mpi_copy (@w{const gcry_mpi_t @var{a}})
3327
3328 Create a new MPI as the exact copy of @var{a}.
3329 @end deftypefun
3330
3331
3332 @deftypefun void gcry_mpi_release (@w{gcry_mpi_t @var{a}})
3333
3334 Release the MPI @var{a} and free all associated resources.  Passing
3335 @code{NULL} is allowed and ignored.  When a MPI stored in the "secure
3336 memory" is released, that memory gets wiped out immediately.
3337 @end deftypefun
3338
3339 @noindent
3340 The simplest operations are used to assign a new value to an MPI:
3341
3342 @deftypefun gcry_mpi_t gcry_mpi_set (@w{gcry_mpi_t @var{w}}, @w{const gcry_mpi_t @var{u}})
3343
3344 Assign the value of @var{u} to @var{w} and return @var{w}.  If
3345 @code{NULL} is passed for @var{w}, a new MPI is allocated, set to the
3346 value of @var{u} and returned.
3347 @end deftypefun
3348
3349 @deftypefun gcry_mpi_t gcry_mpi_set_ui (@w{gcry_mpi_t @var{w}}, @w{unsigned long @var{u}})
3350
3351 Assign the value of @var{u} to @var{w} and return @var{w}.  If
3352 @code{NULL} is passed for @var{w}, a new MPI is allocated, set to the
3353 value of @var{u} and returned.  This function takes an @code{unsigned
3354 int} as type for @var{u} and thus it is only possible to set @var{w} to
3355 small values (usually up to the word size of the CPU).
3356 @end deftypefun
3357
3358 @deftypefun void gcry_mpi_swap (@w{gcry_mpi_t @var{a}}, @w{gcry_mpi_t @var{b}})
3359
3360 Swap the values of @var{a} and @var{b}.
3361 @end deftypefun
3362
3363 @node MPI formats
3364 @section MPI formats
3365
3366 @noindent
3367 The following functions are used to convert between an external
3368 representation of an MPI and the internal one of @acronym{Libgcrypt}.
3369
3370 @deftypefun int gcry_mpi_scan (@w{gcry_mpi_t *@var{r_mpi}}, @w{enum gcry_mpi_format @var{format}}, @w{const unsigned char *@var{buffer}}, @w{size_t @var{buflen}}, @w{size_t *@var{nscanned}})
3371
3372 Convert the external representation of an integer stored in @var{buffer}
3373 with a length of @var{buflen} into a newly created MPI returned which
3374 will be stored at the address of @var{r_mpi}.  For certain formats the
3375 length argument is not required and may be passed as @code{0}.  After a
3376 successful operation the variable @var{nscanned} receives the number of
3377 bytes actually scanned unless @var{nscanned} was given as
3378 @code{NULL}. @var{format} describes the format of the MPI as stored in
3379 @var{buffer}:
3380
3381 @table @code
3382 @item GCRYMPI_FMT_STD
3383 2-complement stored without a length header.
3384
3385 @item GCRYMPI_FMT_PGP
3386 As used by OpenPGP (only defined as unsigned). This is basically
3387 @code{GCRYMPI_FMT_STD} with a 2 byte big endian length header.
3388
3389 @item GCRYMPI_FMT_SSH
3390 As used in the Secure Shell protocol.  This is @code{GCRYMPI_FMT_STD}
3391 with a 4 byte big endian header.
3392
3393 @item GCRYMPI_FMT_HEX
3394 Stored as a C style string with each byte of the MPI encoded as 2 hex
3395 digits.
3396
3397 @item GCRYMPI_FMT_USG
3398 Simple unsigned integer.
3399 @end table
3400
3401 @noindent
3402 Note, that all of the above formats store the integer in big-endian
3403 format (MSB first).
3404 @end deftypefun
3405
3406
3407 @deftypefun int gcry_mpi_print (@w{enum gcry_mpi_format @var{format}}, @w{unsigned char *@var{buffer}}, @w{size_t @var{buflen}}, @w{size_t *@var{nwritten}}, @w{const gcry_mpi_t @var{a}})
3408
3409 Convert the MPI @var{a} into an external representation described by
3410 @var{format} (see above) and store it in the provided @var{buffer}
3411 which has a usable length of at least the @var{buflen} bytes. If
3412 @var{nwritten} is not NULL, it will receive the number of bytes
3413 actually stored in @var{buffer} after a successful operation.
3414 @end deftypefun
3415
3416 @deftypefun int gcry_mpi_aprint (@w{enum gcry_mpi_format @var{format}}, @w{unsigned char **@var{buffer}}, @w{size_t *@var{nbytes}}, @w{const gcry_mpi_t @var{a}})
3417
3418 Convert the MPI @var{a} into an external representation described by
3419 @var{format} (see above) and store it in a newly allocated buffer which
3420 address will be stored in the variable @var{buffer} points to.  The
3421 number of bytes stored in this buffer will be stored in the variable
3422 @var{nbytes} points to, unless @var{nbytes} is @code{NULL}.
3423 @end deftypefun
3424
3425 @deftypefun void gcry_mpi_dump (@w{const gcry_mpi_t @var{a}})
3426
3427 Dump the value of @var{a} in a format suitable for debugging to
3428 Libgcrypt's logging stream.  Note that one leading space but no trailing
3429 space or linefeed will be printed.  It is okay to pass @code{NULL} for
3430 @var{a}.
3431 @end deftypefun
3432
3433
3434 @node Calculations
3435 @section Calculations
3436
3437 @noindent
3438 Basic arithmetic operations:
3439
3440 @deftypefun void gcry_mpi_add (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{gcry_mpi_t @var{v}})
3441
3442 @math{@var{w} = @var{u} + @var{v}}.
3443 @end deftypefun
3444
3445
3446 @deftypefun void gcry_mpi_add_ui (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{unsigned long @var{v}})
3447
3448 @math{@var{w} = @var{u} + @var{v}}.  Note, that @var{v} is an unsigned integer.
3449 @end deftypefun
3450
3451
3452 @deftypefun void gcry_mpi_addm (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{gcry_mpi_t @var{v}}, @w{gcry_mpi_t @var{m}})
3453
3454 @math{@var{w} = @var{u} + @var{v} \bmod @var{m}}.
3455 @end deftypefun
3456
3457 @deftypefun void gcry_mpi_sub (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{gcry_mpi_t @var{v}})
3458
3459 @math{@var{w} = @var{u} - @var{v}}.
3460 @end deftypefun
3461
3462 @deftypefun void gcry_mpi_sub_ui (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{unsigned long @var{v}})
3463
3464 @math{@var{w} = @var{u} - @var{v}}.  @var{v} is an unsigned integer.
3465 @end deftypefun
3466
3467 @deftypefun void gcry_mpi_subm (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{gcry_mpi_t @var{v}}, @w{gcry_mpi_t @var{m}})
3468
3469 @math{@var{w} = @var{u} - @var{v} \bmod @var{m}}.
3470 @end deftypefun
3471
3472 @deftypefun void gcry_mpi_mul (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{gcry_mpi_t @var{v}})
3473
3474 @math{@var{w} = @var{u} * @var{v}}.
3475 @end deftypefun
3476
3477 @deftypefun void gcry_mpi_mul_ui (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{unsigned long @var{v}})
3478
3479 @math{@var{w} = @var{u} * @var{v}}.  @var{v} is an unsigned integer.
3480 @end deftypefun
3481
3482 @deftypefun void gcry_mpi_mulm (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{gcry_mpi_t @var{v}}, @w{gcry_mpi_t @var{m}})
3483
3484 @math{@var{w} = @var{u} * @var{v} \bmod @var{m}}.
3485 @end deftypefun
3486
3487 @deftypefun void gcry_mpi_mul_2exp (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{unsigned long @var{e}})
3488
3489 @c FIXME: I am in need for a real TeX{info} guru:
3490 @c I don't know why TeX can grok @var{e} here.
3491 @math{@var{w} = @var{u} * 2^e}.
3492 @end deftypefun
3493
3494 @deftypefun void gcry_mpi_div (@w{gcry_mpi_t @var{q}}, @w{gcry_mpi_t @var{r}}, @w{gcry_mpi_t @var{dividend}}, @w{gcry_mpi_t @var{divisor}}, @w{int @var{round}})
3495
3496 @math{@var{q} = @var{dividend} / @var{divisor}}, @math{@var{r} =
3497 @var{dividend} \bmod @var{divisor}}.  @var{q} and @var{r} may be passed
3498 as @code{NULL}.  @var{round} should be negative or 0.
3499 @end deftypefun
3500
3501 @deftypefun void gcry_mpi_mod (@w{gcry_mpi_t @var{r}}, @w{gcry_mpi_t @var{dividend}}, @w{gcry_mpi_t @var{divisor}})
3502
3503 @math{@var{r} = @var{dividend} \bmod @var{divisor}}.
3504 @end deftypefun
3505
3506 @deftypefun void gcry_mpi_powm (@w{gcry_mpi_t @var{w}}, @w{const gcry_mpi_t @var{b}}, @w{const gcry_mpi_t @var{e}}, @w{const gcry_mpi_t @var{m}})
3507
3508 @c I don't know why TeX can grok @var{e} here.
3509 @math{@var{w} = @var{b}^e \bmod @var{m}}.
3510 @end deftypefun
3511
3512 @deftypefun int gcry_mpi_gcd (@w{gcry_mpi_t @var{g}}, @w{gcry_mpi_t @var{a}}, @w{gcry_mpi_t @var{b}})
3513
3514 Set @var{g} to the greatest common divisor of @var{a} and @var{b}.  
3515 Return true if the @var{g} is 1.
3516 @end deftypefun
3517
3518 @deftypefun int gcry_mpi_invm (@w{gcry_mpi_t @var{x}}, @w{gcry_mpi_t @var{a}}, @w{gcry_mpi_t @var{m}})
3519
3520 Set @var{x} to the multiplicative inverse of @math{@var{a} \bmod @var{m}}.
3521 Return true if the inverse exists.
3522 @end deftypefun
3523
3524
3525 @node Comparisons
3526 @section Comparisons
3527
3528 @noindent
3529 The next 2 functions are used to compare MPIs:
3530
3531
3532 @deftypefun int gcry_mpi_cmp (@w{const gcry_mpi_t @var{u}}, @w{const gcry_mpi_t @var{v}})
3533
3534 Compare the big integer number @var{u} and @var{v} returning 0 for
3535 equality, a positive value for @var{u} > @var{v} and a negative for
3536 @var{u} < @var{v}.
3537 @end deftypefun
3538
3539 @deftypefun int gcry_mpi_cmp_ui (@w{const gcry_mpi_t @var{u}}, @w{unsigned long @var{v}})
3540
3541 Compare the big integer number @var{u} with the unsigned integer @var{v}
3542 returning 0 for equality, a positive value for @var{u} > @var{v} and a
3543 negative for @var{u} < @var{v}.
3544 @end deftypefun
3545
3546
3547 @node Bit manipulations
3548 @section Bit manipulations
3549
3550 @noindent
3551 There are a couple of functions to get information on arbitrary bits
3552 in an MPI and to set or clear them:
3553
3554 @deftypefun {unsigned int} gcry_mpi_get_nbits (@w{gcry_mpi_t @var{a}})
3555
3556 Return the number of bits required to represent @var{a}.
3557 @end deftypefun
3558
3559 @deftypefun int gcry_mpi_test_bit (@w{gcry_mpi_t @var{a}}, @w{unsigned int @var{n}})
3560
3561 Return true if bit number @var{n} (counting from 0) is set in @var{a}.
3562 @end deftypefun
3563
3564 @deftypefun void gcry_mpi_set_bit (@w{gcry_mpi_t @var{a}}, @w{unsigned int @var{n}})
3565
3566 Set bit number @var{n} in @var{a}.
3567 @end deftypefun
3568
3569 @deftypefun void gcry_mpi_clear_bit (@w{gcry_mpi_t @var{a}}, @w{unsigned int @var{n}})
3570
3571 Clear bit number @var{n} in @var{a}.
3572 @end deftypefun
3573
3574 @deftypefun void gcry_mpi_set_highbit (@w{gcry_mpi_t @var{a}}, @w{unsigned int @var{n}})
3575
3576 Set bit number @var{n} in @var{a} and clear all bits greater than @var{n}.
3577 @end deftypefun
3578
3579 @deftypefun void gcry_mpi_clear_highbit (@w{gcry_mpi_t @var{a}}, @w{unsigned int @var{n}})
3580
3581 Clear bit number @var{n} in @var{a} and all bits greater than @var{n}.
3582 @end deftypefun
3583
3584 @deftypefun void gcry_mpi_rshift (@w{gcry_mpi_t @var{x}}, @w{gcry_mpi_t @var{a}}, @w{unsigned int @var{n}})
3585
3586 Shift the value of @var{a} by @var{n} bits to the right and store the
3587 result in @var{x}.
3588 @end deftypefun
3589
3590 @node Misc
3591 @section Misc
3592
3593 @noindent
3594 The remaining MPI functions take care of very special properties of the
3595 implementation:
3596
3597 @deftypefun gcry_mpi_t gcry_mpi_set_opaque (@w{gcry_mpi_t @var{a}}, @w{void *@var{p}}, @w{unsigned int @var{nbits}})
3598
3599 Store @var{nbits} of the value @var{p} points to in @var{a} and mark
3600 @var{a} as an opaque value (i.e. an value that can't be used for any
3601 math calculation and is only used to store an arbitrary bit pattern in
3602 @var{a}.
3603
3604 WARNING: Never use an opaque MPI for actual math operations.  The only
3605 valid functions are gcry_mpi_get_opaque and gcry_mpi_release.  Use
3606 gcry_mpi_scan to convert a string of arbitrary bytes into an MPI.
3607
3608 @end deftypefun
3609
3610 @deftypefun {void *} gcry_mpi_get_opaque (@w{gcry_mpi_t @var{a}}, @w{unsigned int *@var{nbits}})
3611
3612 Return a pointer to an opaque value stored in @var{a} and return its
3613 size in @var{nbits}.  Note, that the returned pointer is still owned by
3614 @var{a} and that the function should never be used for an non-opaque
3615 MPI.
3616 @end deftypefun
3617
3618 @deftypefun void gcry_mpi_set_flag (@w{gcry_mpi_t @var{a}}, @w{enum gcry_mpi_flag @var{flag}})
3619
3620 Set the @var{flag} for the MPI @var{a}.  Currently only the flag
3621 @code{GCRYMPI_FLAG_SECURE} is allowed to convert @var{a} into an MPI
3622 stored in "secure memory".
3623 @end deftypefun
3624
3625 @deftypefun void gcry_mpi_clear_flag (@w{gcry_mpi_t @var{a}}, @w{enum gcry_mpi_flag @var{flag}})
3626
3627 Clear @var{flag} for the big integer @var{a}.  Note, that this function is
3628 currently useless as no flags are allowed.
3629 @end deftypefun
3630
3631 @deftypefun int gcry_mpi_get_flag (@w{gcry_mpi_t @var{a}}, @w{enum gcry_mpi_flag @var{flag}})
3632
3633 Return true when the @var{flag} is set for @var{a}.
3634 @end deftypefun
3635
3636 @node Utilities
3637 @chapter Utilities
3638
3639 @menu
3640 * Memory allocation::           Functions related with memory allocation.
3641 @end menu
3642
3643 @node Memory allocation
3644 @section Memory allocation
3645
3646 @deftypefun void *gcry_malloc (size_t @var{n})
3647
3648 This function tries to allocate @var{n} bytes of memory.  On success
3649 it returns a pointer to the memory area, in an out-of-core condition,
3650 it returns NULL.
3651 @end deftypefun
3652
3653 @deftypefun void *gcry_malloc_secure (size_t @var{n})
3654 Like @code{gcry_malloc}, but uses secure memory.
3655 @end deftypefun
3656
3657 @deftypefun void *gcry_calloc (size_t @var{n})
3658
3659 This function tries to allocate @var{n} bytes of cleared memory
3660 (i.e. memory that is initialized with zero bytes).  On success it
3661 returns a pointer to the memory area, in an out-of-core condition, it
3662 returns NULL.
3663 @end deftypefun
3664
3665 @deftypefun void *gcry_calloc_secure (size_t @var{n})
3666 Like @code{gcry_calloc}, but uses secure memory.
3667 @end deftypefun
3668
3669 @deftypefun void *gcry_realloc (void *@var{p}, size_t @var{n})
3670
3671 This function tries to resize the memory area pointed to by @var{p} to
3672 @var{n} bytes.  On success it returns a pointer to the new memory
3673 area, in an out-of-core condition, it returns NULL.  Depending on
3674 wether the memory pointed to by @var{p} is secure memory or not,
3675 gcry_realloc tries to use secure memory as well.
3676 @end deftypefun
3677
3678 @deftypefun void gcry_free (void *@var{p})
3679 Release the memory area pointed to by @var{p}.
3680 @end deftypefun
3681
3682 @c **********************************************************
3683 @c *******************  Appendices  *************************
3684 @c **********************************************************
3685
3686 @include lgpl.texi
3687
3688 @include gpl.texi
3689
3690 @node Concept Index
3691 @unnumbered Concept Index
3692
3693 @printindex cp
3694
3695 @node Function and Data Index
3696 @unnumbered Function and Data Index
3697
3698 @printindex fn
3699
3700 @bye
3701
3702   /* Version check should be the very first gcry call because it
3703      makes sure that constructor functrions are run. */
3704   if (!gcry_check_version (GCRYPT_VERSION))
3705     die ("version mismatch\n");
3706   /* Many applications don't require secure memory, so they should
3707      disable it right away.  There won't be a problem unless one makes
3708      use of a feature which requires secure memoery - in that case the
3709      process would abort becuase the secmem is not initialized. */
3710   gcry_control (GCRYCTL_DISABLE_SECMEM, 0);
3711
3712   /* .. add whatever initialization you want, but better don't make calls
3713         to libgcrypt from more than one thread ... */
3714
3715   /* Tell Libgcrypt that initialization has completed. */
3716   gcry_control (GCRYCTL_INITIALIZATION_FINISHED, 0);
3717
3718
3719 If you require secure memory, this code should be used: 
3720
3721   if (!gcry_check_version (GCRYPT_VERSION))
3722     die ("version mismatch\n");
3723   /* We don't want to see any warnings, e.g. because we have not yet
3724     parsed options which might be used to suppress such warnings */
3725   gcry_control (GCRYCTL_SUSPEND_SECMEM_WARN);
3726
3727   /* ... */
3728
3729   /* Allocate a pool of 16k secure memory.  This also drops priviliges
3730      on some systems. */
3731   gcry_control (GCRYCTL_INIT_SECMEM, 16384, 0);
3732
3733   /* It is now okay to let Libgcrypt complain when there was/is a problem
3734      with the secure memory. */
3735   gcry_control (GCRYCTL_RESUME_SECMEM_WARN);
3736
3737   /* Tell Libgcrypt that initialization has completed. */
3738   gcry_control (GCRYCTL_INITIALIZATION_FINISHED, 0);
3739
3740
3741 This sounds a bit complicated but has the advantage that the caller
3742 must decide whether he wants secure memory or not - there is no
3743 default.
3744
3745 It is important that this initialization is not done by a library but
3746 in the application.  The library might want to check for finished
3747 initialization using:
3748
3749   if (!gcry_control (GCRYCTL_INITIALIZATION_FINISHED_P))
3750     return MYLIB_ERROR_LIBGCRYPT_NOT_INITIALIZED;
3751
3752
3753 @c  LocalWords:  int HD
3754