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