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