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