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