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