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