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