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