* cipher.c (gcry_cipher_open): Don't reject CTS flag.
[libgcrypt.git] / doc / gcrypt.texi
1 \input texinfo                  @c -*- Texinfo -*-
2 @c Copyright (C) 2000, 2002 Free Software Foundation, Inc.
3 @c 
4 @c This file is part of the libgcrypt.
5 @c
6 @c Permission is granted to copy, distribute and/or modify this document
7 @c under the terms of the GNU Free Documentation License, Version 1.1 or
8 @c any later version published by the Free Software Foundation; with no
9 @c Invariant Sections, with no the Front-Cover texts, and with no
10 @c Back-Cover Texts. 
11 @c A copy of the license is included in the file 'fdl.texi'.
12 @c
13 @setfilename gcrypt.info
14 @settitle The `Libgcrypt' Reference Manual
15
16 @dircategory GNU Libraries
17 @direntry
18 * libgcrypt: (gcrypt) Cryptographic function library.
19 @end direntry
20
21 @include version.texi
22
23 @c Unify some of the indices.
24 @syncodeindex tp fn
25 @syncodeindex pg fn
26
27 @ifinfo
28 This file documents the `Libgcrypt' library.
29
30 This is Edition @value{EDITION}, last updated @value{UPDATED}, of
31 @cite{The `Libgcrypt' Reference Manual}, for Version
32 @value{VERSION}.
33
34 Copyright @copyright{} 2000, 2002 Free Software Foundation, Inc.
35
36 Permission is granted to copy, distribute and/or modify this document
37 under the terms of the GNU Free Documentation License, Version 1.1 or
38 any later version published by the Free Software Foundation; with no
39 Invariant Sections, with no the Front-Cover texts, and with no
40 Back-Cover Texts.  A copy of the license is included in the section
41 entitled ``GNU Free Documentation License''.
42 @end ifinfo
43
44 @iftex
45 @shorttitlepage The `Libgcrypt' Reference Manual
46 @end iftex
47 @titlepage
48 @center @titlefont{The `Libgcrypt'}
49 @sp 1
50 @center @titlefont{Reference Manual}
51 @sp 6
52 @center Edition @value{EDITION}
53 @sp 1
54 @center last updated @value{UPDATED}
55 @sp 1
56 @center for version @value{VERSION}
57 @page
58 @vskip 0pt plus 1filll
59 Copyright @copyright{} 2000, 2002 Free Software Foundation, Inc.
60
61 Permission is granted to copy, distribute and/or modify this document
62 under the terms of the GNU Free Documentation License, Version 1.1 or
63 any later version published by the Free Software Foundation; with no
64 Invariant Sections, with no the Front-Cover texts, and with no
65 Back-Cover Texts.  A copy of the license is included in the section
66 entitled ``GNU Free Documentation License''.
67 @end titlepage
68 @page
69
70 @ifnottex
71 @node Top
72 @top Main Menu
73 This is Edition @value{EDITION}, last updated @value{UPDATED}, of
74 @cite{The `Libgcrypt' Reference Manual}, for Version
75 @value{VERSION} of the @acronym{GPGME} library.
76 @end ifnottex
77
78 @menu
79 * Introduction::                How to use this manual.
80 * Preparation::                 What you should do before using the library.
81 * Cipher Functions::            All about ciphers.
82 * Hash Functions::              How to use cryptographic hash functions.
83 * Public Key Functions::        How to use asymmetric encryption.
84 * Random Numbers::              How to create random.
85 * Utilities::                   Helper functions.
86 * Error Handling::              Error codes and such.
87
88 Appendices
89
90 * Library Copying::             The GNU Lesser General Public License
91                                 says how you can copy and share `Libgcrypt'.
92 * Copying::                     The GNU General Public License says how you
93                                 can copy and share some parts of `Libgcrypt'.
94 * Free Documentation License::  This manual is under the GNU Free
95                                 Documentation License.
96
97 Indices
98
99 * Concept Index::               Index of concepts and programs.
100 * Function and Data Index::     Index of functions, variables and data types.
101
102 @detailmenu
103 @end detailmenu
104 @end menu
105
106 @c **********************************************************
107 @c *******************  Introduction  ***********************
108 @c **********************************************************
109 @node Introduction
110 @chapter Introduction
111 `Libgcrypt' is a library to provide cryptographic building blocks.
112
113 @menu
114 * Getting Started::             
115 * Features::                    
116 * Overview::                    
117 @end menu
118
119 @node Getting Started
120 @section Getting Started
121
122 This manual documents the `Libgcrypt' library programming interface.
123 All functions and data types provided by the library are explained.
124
125 The reader is assumed to possess basic knowledge about applied
126 cryptography.
127
128 This manual can be used in several ways.  If read from the beginning
129 to the end, it gives a good introduction into the library and how it
130 can be used in an application.  Forward references are included where
131 necessary.  Later on, the manual can be used as a reference manual to
132 get just the information needed about any particular interface of the
133 library.  Experienced programmers might want to start looking at the
134 examples at the end of the manual, and then only read up those parts
135 of the interface which are unclear.
136
137
138 @node Features
139 @section Features
140
141 `Libgcrypt' might have a couple of advantages over other libraries doing
142 a similar job.
143
144 @table @asis
145 @item It's Free Software
146 Anybody can use, modify, and redistribute it under the terms of the GNU
147 Lesser General Public License (@pxref{Library Copying}).  Note, that
148 some parts (which are not needed on a GNU or GNU/Linux system) are
149 subject to the terms of the GNU General Public License
150 (@pxref{Copying}); please see the README file of the distribution for of
151 list of these parts.
152
153 @item It encapsulates the low level cryptography
154 `Libgcrypt' a high level interface to cryptographic building blocks
155 using an extendable and flexible API.
156
157 @end table
158
159
160 @node Overview
161 @section Overview
162
163 Blurb
164
165 The `Libgcrypt' library is thread-safe.  Well, we hope so ;-)
166
167
168 @c **********************************************************
169 @c *******************  Preparation  ************************
170 @c **********************************************************
171 @node Preparation
172 @chapter Preparation
173
174 To use `Libgcrypt', you have to perform some changes to your sources and
175 the build system.  The necessary changes are small and explained in the
176 following sections.  At the end of this chapter, it is described how the
177 library is initialized, and how the requirements of the library are
178 verified.
179
180 @menu
181 * Header::                      
182 * Version Check::               
183 * Building the source::         
184 @end menu
185
186
187 @node Header
188 @section Header
189
190 All interfaces (data types and functions) of the library are defined
191 in the header file `gcrypt.h'.  You must include this in all programs
192 using the library, either directly or through some other header file,
193 like this:
194
195 @example
196 #include <gcrypt.h>
197 @end example
198
199 The name space of `Libgcrypt' is @code{gcry_*} for function names,
200 @code{Gcry*} for data types and @code{GCRY_*} for other symbols.  In
201 addition the same name prefixes with one prepended underscore are
202 reserved for internal use and should never be used by an application.
203
204 @node Version Check
205 @section Version Check
206
207 It is often desirable to check that the version of `Libgcrypt' used is
208 indeed one which fits all requirements.  Even with binary compatibility
209 new features may have been introduced but due to problem with the
210 dynamic linker an old version is actually used.  So you may want to
211 check that the version is okay right after program startup.
212
213 @deftypefun const char *gcry_check_version (const char *@var{req_version})
214
215 Check that the the version of the library is at minimum the one given as
216 a string in @var{req_version} and return the actual version string of
217 the library; return NULL if the condition is not met.  If @code{NULL} is
218 passed to this function no check is done and only the version string is
219 returned.  It is a pretty good idea to run this function as soon as
220 possible, because it may also intializes some subsystems.  In a
221 multithreaded environment if should be called before any more threads
222 are created.
223 @end deftypefun
224
225 @node Building the source
226 @section Building the source
227
228 If you want to compile a source file including the `gcrypt.h' header
229 file, you must make sure that the compiler can find it in the
230 directory hierarchy.  This is accomplished by adding the path to the
231 directory in which the header file is located to the compilers include
232 file search path (via the @option{-I} option).
233
234 However, the path to the include file is determined at the time the
235 source is configured.  To solve this problem, `Libgcrypt' ships with a small
236 helper program @command{libgcrypt-config} that knows the path to the
237 include file and other configuration options.  The options that need
238 to be added to the compiler invocation at compile time are output by
239 the @option{--cflags} option to @command{libgcrypt-config}.  The following
240 example shows how it can be used at the command line:
241
242 @example
243 gcc -c foo.c `libgcrypt-config --cflags`
244 @end example
245
246 Adding the output of @samp{libgcrypt-config --cflags} to the compilers
247 command line will ensure that the compiler can find the `Libgcrypt' header
248 file.
249
250 A similar problem occurs when linking the program with the library.
251 Again, the compiler has to find the library files.  For this to work,
252 the path to the library files has to be added to the library search path
253 (via the @option{-L} option).  For this, the option @option{--libs} to
254 @command{libgcrypt-config} can be used.  For convenience, this option
255 also outputs all other options that are required to link the program
256 with the `Libgcrypt' libararies (in particular, the @samp{-lgcrypt}
257 option).  The example shows how to link @file{foo.o} with the `Libgcrypt'
258 library to a program @command{foo}.
259
260 @example
261 gcc -o foo foo.o `libgcrypt-config --libs`
262 @end example
263
264 Of course you can also combine both examples to a single command by
265 specifying both options to @command{libgcrypt-config}:
266
267 @example
268 gcc -o foo foo.c `libgcrypt-config --cflags --libs`
269 @end example
270
271
272 @c **********************************************************
273 @c *******************  Ciphers  ****************************
274 @c **********************************************************
275 @c @include cipher-ref.texi
276 @node Cipher Functions
277 @chapter Cipher Functions
278
279
280 @deftypefun GCRY_CIPHER_HD gcry_cipher_open (int @var{algo}, int @var{mode}, unsigned int @var{flags})
281
282 This function creates the context required for most of the othercipher
283 functions.  In case of an error @code{NULL} is returned.
284 @end deftypefun
285
286 @deftypefun void gcry_cipher_close (GCRY_CIPHER_HD @var{h})
287
288 This function releases the context created by @code{gcry_cipher_open}.
289 @end deftypefun
290
291
292 @deftypefun int gcry_cipher_ctl (GCRY_CIPHER_HD @var{h}, int @var{cmd}, void *@var{buffer}, size_t @var{buflen})
293
294 @code{gcry_cipher_ctl} controls various aspects of the cipher module and
295 specific cipher contexts.  Usually some more specialzed functions are
296 used for this purpose.
297 @end deftypefun
298
299 @deftypefun int gcry_cipher_setkey (GCRY_CIPHER_HD @var{h}, void *@var{k}, size_t @var{l})
300
301 Set the key used for encryption or decryption.  Note, that this is
302 implemented as a macro.
303 @end deftypefun
304
305 @deftypefun int gcry_cipher_setiv (GCRY_CIPHER_HD @var{h}, void *@var{k}, size_t @var{l})
306
307 Set the initialization vector used for encryption or decryption.  Note,
308 that this is implemented as a macro.
309 @end deftypefun
310
311 @deftypefun int gcry_cipher_sync (GCRY_CIPHER_HD @var{h})
312
313 Peform the a ``sync'' operation which is only used with certain modes.
314 @end deftypefun
315
316
317 @c ***********************************************
318 @c ***********  cipher info   ********************
319 @c ***********************************************
320 @deftypefun int gcry_cipher_info (GCRY_CIPHER_HD @var{h}, int @var{what}, void *@var{buffer}, size_t *@var{nbytes})
321
322 @code{gcry_cipher_info} is used to retrieve various
323 information about a cipher context or the cipher module in general.
324 Currently no information is available.
325 @end deftypefun
326
327 @deftypefun int gcry_cipher_algo_info (int @var{algo}, int @var{what}, void *@var{buffer}, size_t *@var{nbytes})
328
329 fixme
330
331 @end deftypefun
332
333 @deftypefun const char *gcry_cipher_algo_name (int @var{algo})
334
335 @code{gcry_cipher_algo_name} returns a string with the name of the
336 cipher algorithm @var{algo}.  If the algorithm s not known or an other
337 error occured, an empty string is return.  This function will never
338 return @code{NULL}.
339 @end deftypefun
340
341 @deftypefun int gcry_cipher_map_name (const char *@var{name})
342
343 @code{gcry_cipher_map_name} returns the algorithm identifier for the
344 cipher algorithm described by the string @var{name}.  If this algorithm
345 is not available @code{0} is returned.
346 @end deftypefun
347
348 @deftypefun int gcry_cipher_mode_from_oid (const char *@var{string})
349
350 Return the cipher mode associated with an @acronym{ASN.1} object
351 identifier.  The object identifier is expected to be in the
352 @acronym{IETF}-style dotted decimal notation.  The function returns
353 @code{0} for an unknown object identifier or when no mode is associated
354 with it.
355 @end deftypefun
356
357 @c ******************************************
358 @c *******  cipher en/decrypt  **************
359 @c ******************************************
360
361 @deftypefun int gcry_cipher_encrypt (GCRY_CIPHER_HD @var{h}, unsigned char *{out}, size_t @var{outsize}, const unsigned char *@var{in}, size_t @var{inlen})
362
363 @code{gcry_cipher_encrypt} is used to encrypt the data.
364 This function can either work in place or with two buffers.
365 Overlapping buffers are not allowed.
366 @end deftypefun
367
368 @deftypefun int gcry_cipher_decrypt (GCRY_CIPHER_HD @var{h}, unsigned char *{out}, size_t @var{outsize}, const unsigned char *@var{in}, size_t @var{inlen})
369
370 @code{gcry_cipher_encrypt} is used to decrypt the data.
371 This function can either work in place or with two buffers.
372 Overlapping buffers are not allowed.
373 @end deftypefun
374
375 @c **********************************************************
376 @c *******************  Hash Functions  *********************
377 @c **********************************************************
378 @node Hash Functions
379 @chapter Hash Functions
380
381 How to use cryptographic hash functions.
382
383
384 @c <refentry>
385 @c   <refnamediv>
386 @c     <refname>gcry_md_open</refname>
387 @c     <refname>gcry_md_enable</refname>
388 @c     <refname>gcry_md_close</refname>
389 @c     <refpurpose>create and destroy a message digest context</refpurpose>
390 @c   </refnamediv>
391 @c 
392 @c   <refsynopsisdiv>
393 @c     <funcsynopsis>
394 @c       <funcsynopsisinfo>
395 @c       #include &lt;gcrypt.h&gt;
396 @c       </funcsynopsisinfo>
397 @c       <funcprototype>
398 @c         <funcdef>GCRY_MD_HD <function>gcry_md_open</function></funcdef>
399 @c         <paramdef>int <parameter>algo</parameter></paramdef>
400 @c         <paramdef>unsigned int <parameter>flags</parameter></paramdef>
401 @c       </funcprototype>
402 @c       <funcprototype>
403 @c         <funcdef>void <function>gcry_md_enable</function></funcdef>
404 @c         <paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
405 @c         <paramdef>int <parameter>algo</parameter></paramdef>
406 @c       </funcprototype>
407 @c       <funcprototype>
408 @c         <funcdef>void <function>gcry_md_close</function></funcdef>
409 @c         <paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
410 @c       </funcprototype>
411 @c     </funcsynopsis>
412 @c   </refsynopsisdiv>
413 @c 
414 @c 
415 @c   <refsect1><title>Description</title>
416 @c   <para>
417 @c   <indexterm><primary>hash functions</primary>
418 @c              <secondary>gcry_md_open</secondary>
419 @c              </indexterm>
420 @c   <indexterm><primary>hash functions</primary>
421 @c              <secondary>gcry_md_enable</secondary>
422 @c              </indexterm>
423 @c   <indexterm><primary>hash functions</primary>
424 @c              <secondary>gcry_md_close</secondary>
425 @c              </indexterm>
426 @c   <function>gcry_md_open</function> creates the context required for
427 @c   the message digest functions.  The hash algorithm may optionally be
428 @c   specified. It is possible to use these functions as MAC functons; therefore
429 @c   the flag <literal/GCRY_MD_FLAG_HMAC/ must be given along with the
430 @c   hash functions.  Other MAC algorithms than  HMAC are currently not
431 @c   supported.  The key for the MAC must be set using
432 @c   the <function>gcry_md_setkey</> function.
433 @c   <function>gcry_md_close</function> releases all resources associated
434 @c   with the context.
435 @c   <function>gcry_md_enable</function> may be used to enable hash
436 @c   algorithms.  This function may be used multiple times to create
437 @c   a hash context for multiple algorithms.  Adding an already enabled algorithm
438 @c   has no effect.  A algorithm must be enabled prios to calculate hash
439 @c   algorithms.
440 @c   </para>
441 @c </refentry>
442 @c 
443 @c <!--**********************************************
444 @c ***********  md_copy *****************************
445 @c ***********************************************-->
446 @c <refentry>
447 @c   <refnamediv>
448 @c     <refname>gcry_md_copy</refname>
449 @c     <refpurpose>create and copy of a message digest context</refpurpose>
450 @c   </refnamediv>
451 @c 
452 @c   <refsynopsisdiv>
453 @c     <funcsynopsis>
454 @c       <funcsynopsisinfo>
455 @c       #include &lt;gcrypt.h&gt;
456 @c       </funcsynopsisinfo>
457 @c       <funcprototype>
458 @c         <funcdef>GCRY_MD_HD <function>gcry_md_copy</function></funcdef>
459 @c         <paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
460 @c       </funcprototype>
461 @c     </funcsynopsis>
462 @c   </refsynopsisdiv>
463 @c 
464 @c 
465 @c   <refsect1><title>Description</title>
466 @c   <para>
467 @c   <indexterm><primary>hash functions</primary>
468 @c              <secondary>gcry_md_copy</secondary>
469 @c              </indexterm>
470 @c   <function>gcry_md_copy</function> creates an excat copy of the given context.
471 @c   This is useful to calculate hashes with a common initial part of the
472 @c   plaintext.
473 @c   </para>
474 @c </refentry>
475 @c 
476 @c <!--**********************************************
477 @c ***********  md_reset  ***************************
478 @c ***********************************************-->
479 @c <refentry>
480 @c   <refnamediv>
481 @c     <refname>gcry_md_reset</refname>
482 @c     <refpurpose>reset a message digest context</refpurpose>
483 @c   </refnamediv>
484 @c 
485 @c   <refsynopsisdiv>
486 @c     <funcsynopsis>
487 @c       <funcsynopsisinfo>
488 @c       #include &lt;gcrypt.h&gt;
489 @c       </funcsynopsisinfo>
490 @c       <funcprototype>
491 @c         <funcdef>void <function>gcry_md_reset</function></funcdef>
492 @c         <paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
493 @c       </funcprototype>
494 @c     </funcsynopsis>
495 @c   </refsynopsisdiv>
496 @c 
497 @c 
498 @c   <refsect1><title>Description</title>
499 @c   <para>
500 @c   <indexterm><primary>hash functions</primary>
501 @c              <secondary>gcry_md_reset</secondary>
502 @c              </indexterm>
503 @c   <function>gcry_md_reset</function> is used to reuse a message context
504 @c   without the overhead of an open and close operation.
505 @c   </para>
506 @c </refentry>
507 @c 
508 @c 
509 @c <!--**********************************************
510 @c ***********  md_ctl  *****************************
511 @c ***********************************************-->
512 @c <refentry>
513 @c   <refnamediv>
514 @c     <refname>gcry_md_ctl</refname>
515 @c     <refname>gcry_md_final</refname>
516 @c     <refname>gcry_md_setkey</refname>
517 @c     <refpurpose>perform special operations on a digest context</refpurpose>
518 @c   </refnamediv>
519 @c 
520 @c   <refsynopsisdiv>
521 @c     <funcsynopsis>
522 @c       <funcsynopsisinfo>
523 @c       #include &lt;gcrypt.h&gt;
524 @c       </funcsynopsisinfo>
525 @c       <funcprototype>
526 @c         <funcdef>int <function>gcry_md_ctl</function></funcdef>
527 @c         <paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
528 @c         <paramdef>int <parameter>cmd</parameter></paramdef>
529 @c         <paramdef>unsigned char * <parameter>buffer</parameter></paramdef>
530 @c         <paramdef>size_t <parameter>buflen</parameter></paramdef>
531 @c       </funcprototype>
532 @c     </funcsynopsis>
533 @c   </refsynopsisdiv>
534 @c 
535 @c 
536 @c   <refsect1><title>Description</title>
537 @c   <para>
538 @c   <indexterm><primary>hash functions</primary>
539 @c              <secondary>gcry_md_ctl</secondary>
540 @c              </indexterm>
541 @c   <function>gcry_md_ctl</function> is a multi-purpose function
542 @c   to control the behaviour of all gcry_md functions or one instance
543 @c   of it.
544 @c   </para>
545 @c   <para>
546 @c   Currently defined values for <parameter>cmd</> are:
547 @c   </para>
548 @c   <para>
549 @c     <literal>GCRYCTL_FINALIZE</> and the convenience macro
550 @c     <function>gcry_md_final(a)</>
551 @c   </para>
552 @c   <para>
553 @c     <literal>GCRYCTL_SET_KEY</> and the convenience macro
554 @c     <function>gcry_md_setkey(a)</>.  This is used to turn these
555 @c     hash functions into MAC functions.       The key may be any string
556 @c     of the speicified length.  The type of the MAC is determined
557 @c     by special flags set with the open function.
558 @c     NEW:  There is now a function to do this
559 @c   </para>
560 @c </refentry>
561 @c 
562 @c <!--**********************************************
563 @c ***********  md_write, putc  *********************
564 @c ***********************************************-->
565 @c <refentry>
566 @c   <refnamediv>
567 @c     <refname>gcry_md_write</refname>
568 @c     <refname>gcry_md_putc</refname>
569 @c     <refpurpose>calculate the message digest of a buffer</refpurpose>
570 @c   </refnamediv>
571 @c 
572 @c   <refsynopsisdiv>
573 @c     <funcsynopsis>
574 @c       <funcsynopsisinfo>
575 @c       #include &lt;gcrypt.h&gt;
576 @c       </funcsynopsisinfo>
577 @c       <funcprototype>
578 @c         <funcdef>int <function>gcry_md_write</function></funcdef>
579 @c         <paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
580 @c         <paramdef>unsigned char * <parameter>buffer</parameter></paramdef>
581 @c         <paramdef>size_t <parameter>buflen</parameter></paramdef>
582 @c       </funcprototype>
583 @c       <funcprototype>
584 @c         <funcdef>int <function>gcry_md_putc</function></funcdef>
585 @c         <paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
586 @c         <paramdef>int <parameter>c</parameter></paramdef>
587 @c       </funcprototype>
588 @c     </funcsynopsis>
589 @c   </refsynopsisdiv>
590 @c 
591 @c 
592 @c   <refsect1><title>Description</title>
593 @c   <para>
594 @c   <indexterm><primary>hash functions</primary>
595 @c              <secondary>gcry_md_write</secondary></indexterm>
596 @c   <indexterm><primary>hash functions</primary>
597 @c              <secondary>gcry_md_putc</secondary></indexterm>
598 @c   <function>gcry_md_write</function> is used to actually calulate the message
599 @c   digest of a buffer.  This function updates the internal state of the message
600 @c   digest.
601 @c   </para>
602 @c   <para>
603 @c   <function>gcry_md_putc</function> is a macro which is used to update
604 @c   the message digest by one byte.  this is the preferred way to calculate
605 @c   a digest if only a few bytes at a time are available.
606 @c   </para>
607 @c </refentry>
608 @c 
609 @c <!--**********************************************
610 @c ***********  md_read *****************************
611 @c ***********************************************-->
612 @c <refentry>
613 @c   <refnamediv>
614 @c     <refname>gcry_md_read</refname>
615 @c     <refpurpose>read out the message digest</refpurpose>
616 @c   </refnamediv>
617 @c 
618 @c   <refsynopsisdiv>
619 @c     <funcsynopsis>
620 @c       <funcsynopsisinfo>
621 @c       #include &lt;gcrypt.h&gt;
622 @c       </funcsynopsisinfo>
623 @c       <funcprototype>
624 @c         <funcdef>unsigned char * <function>gcry_md_read</function></funcdef>
625 @c         <paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
626 @c         <paramdef>int <parameter>algo</parameter></paramdef>
627 @c       </funcprototype>
628 @c     </funcsynopsis>
629 @c   </refsynopsisdiv>
630 @c 
631 @c 
632 @c   <refsect1><title>Description</title>
633 @c   <para>
634 @c   <indexterm><primary>hash functions</primary>
635 @c              <secondary>gcry_md_read</secondary>
636 @c              </indexterm>
637 @c   <indexterm><primary>hash functions</primary>
638 @c              <secondary>gcry_md_putc</secondary>
639 @c              </indexterm>
640 @c   <function>gcry_md_read</function> returns the message digest after finalizing
641 @c   the calculation.  This function may be used as often as required but it
642 @c   will alwas return the same value for one handle.  The returned message
643 @c   digest is allocated within the message context and therefore valid until
644 @c   the conext is released.  <parameter>algo</> may be given as 0 to return the
645 @c   only enbaled message digest or it may specify one of the enabled algorithms.
646 @c   The function will return NULL if the algorithm has not been enabled.
647 @c   </para>
648 @c </refentry>
649 @c 
650 @c 
651 @c <!--**********************************************
652 @c ***********  md_info  ****************************
653 @c ***********************************************-->
654 @c <refentry>
655 @c   <refnamediv>
656 @c     <refname>gcry_md_info</refname>
657 @c     <refpurpose>get information about a handle</refpurpose>
658 @c   </refnamediv>
659 @c 
660 @c   <refsynopsisdiv>
661 @c     <funcsynopsis>
662 @c       <funcsynopsisinfo>
663 @c       #include &lt;gcrypt.h&gt;
664 @c       </funcsynopsisinfo>
665 @c       <funcprototype>
666 @c         <funcdef>int <function>gcry_md_info</function></funcdef>
667 @c         <paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
668 @c         <paramdef>int             <parameter>what</parameter></paramdef>
669 @c         <paramdef>void * <parameter>buffer</parameter></paramdef>
670 @c         <paramdef>size_t <parameter>buflen</parameter></paramdef>
671 @c       </funcprototype>
672 @c     </funcsynopsis>
673 @c   </refsynopsisdiv>
674 @c 
675 @c   <refsect1><title>Description</title>
676 @c   <para>
677 @c   <indexterm><primary>hash functions</primary>
678 @c              <secondary>gcry_md_info</secondary>
679 @c              </indexterm>
680 @c   <function>gcry_md_info</function> returns some information about the
681 @c   handle or an global parameter.
682 @c   </para>
683 @c   <para>
684 @c   The only defined value for <parameter>what</> is
685 @c   <literal>GCRYCTL_IS_SECURE</literal> to return whether the handle
686 @c   has been allocated in secure memory.       Buffer and buflen are not needed
687 @c   in this cases.  The convenience macro <function>gcry_md_is_secure(a)</>
688 @c   may be also used for this purpose.
689 @c   </para>
690 @c </refentry>
691 @c 
692 @c 
693 @c <!--**********************************************
694 @c ***********  md_algo_info  ***********************
695 @c ***********************************************-->
696 @c <refentry>
697 @c   <refnamediv>
698 @c     <refname>gcry_md_algo_info</refname>
699 @c     <refname>gcry_md_test_algo</refname>
700 @c     <refname>gcry_md_get_algo_dlen</refname>
701 @c     <refpurpose>get information about an algorithm</refpurpose>
702 @c   </refnamediv>
703 @c 
704 @c   <refsynopsisdiv>
705 @c     <funcsynopsis>
706 @c       <funcsynopsisinfo>
707 @c       #include &lt;gcrypt.h&gt;
708 @c       </funcsynopsisinfo>
709 @c       <funcprototype>
710 @c         <funcdef>int <function>gcry_md_algo_info</function></funcdef>
711 @c         <paramdef>int             <parameter>algo</parameter></paramdef>
712 @c         <paramdef>int             <parameter>what</parameter></paramdef>
713 @c         <paramdef>void * <parameter>buffer</parameter></paramdef>
714 @c         <paramdef>size_t <parameter>buflen</parameter></paramdef>
715 @c       </funcprototype>
716 @c       <funcprototype>
717 @c         <funcdef>unsigned int <function>gcry_md_get_algo_dlen</function></funcdef>
718 @c         <paramdef>int <parameter>algo</parameter></paramdef>
719 @c       </funcprototype>
720 @c     </funcsynopsis>
721 @c   </refsynopsisdiv>
722 @c 
723 @c   <refsect1><title>Description</title>
724 @c   <para>
725 @c   <indexterm><primary>hash functions</primary>
726 @c              <secondary>gcry_md_algo_info</secondary>
727 @c              </indexterm>
728 @c   <function>gcry_md_algo_info</function> returns some information about an
729 @c   algorithm.  On error the value -1 is return and a more detailed error
730 @c   description is available with <function>gcry_errno</>.
731 @c   </para>
732 @c   <para>
733 @c   The defined values for <parameter>what</> are
734 @c   <literal>GCRYCTL_TEST_ALGO</literal> to return whether the algorithm
735 @c   is supported. Buffer and buflen are not needed
736 @c   in this cases.  The convenience macro <function>gcry_md_test_algo(a)</>
737 @c   may be used for this purpose.
738 @c   </para>
739 @c   <para>
740 @c   <literal>GCRYCTL_GET_ASNOID</literal> to return whether the ASN.1
741 @c   object identifier.  IF buffer is specified as NULL, only the required
742 @c   length for the buffer is returned.
743 @c   </para>
744 @c   <para>
745 @c   <indexterm><primary>hash functions</primary>
746 @c              <secondary>gcry_md_get_algo_dlen</secondary>
747 @c              </indexterm>
748 @c   <function>gcry_md_get_algo_dlen</function> returns the length of the
749 @c   digest for a given algorithm in bytes.
750 @c   </para>
751 @c </refentry>
752 @c 
753 @c 
754 @c <!--**********************************************
755 @c ***********  md_algo_name, map_name  *************
756 @c ***********************************************-->
757 @c <refentry>
758 @c   <refnamediv>
759 @c     <refname>gcry_md_algo_name</refname>
760 @c     <refname>gcry_md_map_name</refname>
761 @c     <refpurpose>map algorithm to string</refpurpose>
762 @c   </refnamediv>
763 @c 
764 @c   <refsynopsisdiv>
765 @c     <funcsynopsis>
766 @c       <funcsynopsisinfo>
767 @c       #include &lt;gcrypt.h&gt;
768 @c       </funcsynopsisinfo>
769 @c       <funcprototype>
770 @c         <funcdef>const char * <function>gcry_md_algo_name</function></funcdef>
771 @c         <paramdef>int             <parameter>algo</parameter></paramdef>
772 @c       </funcprototype>
773 @c       <funcprototype>
774 @c         <funcdef>int <function>gcry_md_map_name</function></funcdef>
775 @c         <paramdef>const char*<parameter>name</parameter></paramdef>
776 @c       </funcprototype>
777 @c     </funcsynopsis>
778 @c   </refsynopsisdiv>
779 @c 
780 @c   <refsect1><title>Description</title>
781 @c   <para>
782 @c   <indexterm><primary>hash functions</primary>
783 @c              <secondary>gcry_md_algo_name</secondary>
784 @c              </indexterm>
785 @c   <indexterm><primary>hash functions</primary>
786 @c              <secondary>gcry_md_map_name</secondary>
787 @c              </indexterm>
788 @c   These both functions are used to map a string with the algorithm name to
789 @c   the internal algorithm identifier value and vice versa.
790 @c   </para>
791 @c   <para>
792 @c   <function>gcry_md_algo_name</> never returns NULL even in cases where the
793 @c   algorithm string is not available.  Instead a string consisting of a
794 @c   single question mark is returned.  Do not use this function to test
795 @c   for the existence of an algorithm.
796 @c   </para>
797 @c   <para>
798 @c   <function>gcry_md_map_name</> returns 0 if the algorithm is not known
799 @c   to &libgcrypt;.
800 @c   </para>
801 @c </refentry>
802 @c 
803 @c 
804 @c 
805 @c <!--**********************************************
806 @c ***********  md_hash_buffer  *********************
807 @c ***********************************************-->
808 @c <refentry>
809 @c   <refnamediv>
810 @c     <refname>gcry_md_hash_buffer</refname>
811 @c     <refpurpose>fast message calculation</refpurpose>
812 @c   </refnamediv>
813 @c 
814 @c   <refsynopsisdiv>
815 @c     <funcsynopsis>
816 @c       <funcsynopsisinfo>
817 @c       #include &lt;gcrypt.h&gt;
818 @c       </funcsynopsisinfo>
819 @c       <funcprototype>
820 @c         <funcdef>int <function>gcry_md_hash_buffer</function></funcdef>
821 @c         <paramdef>int  <parameter>algo</parameter></paramdef>
822 @c         <paramdef>char * <parameter>digest</parameter></paramdef>
823 @c         <paramdef>const char * <parameter>buffer</parameter></paramdef>
824 @c         <paramdef>size_t <parameter>buflen</parameter></paramdef>
825 @c       </funcprototype>
826 @c     </funcsynopsis>
827 @c   </refsynopsisdiv>
828 @c 
829 @c   <refsect1><title>Description</title>
830 @c   <para>
831 @c   <indexterm><primary>hash functions</primary>
832 @c              <secondary>gcry_md_hash_buffer</secondary>
833 @c              </indexterm>
834 @c   <function>gcry_md_hash_buffer</function> is a shortcut function
835 @c   to calculate a message digest of a buffer.  This function does not require
836 @c   a context and immediatley returns the message digest.
837 @c   <parameter>digest</> must be string large enough to hold the digest
838 @c   given by algo.  This length may be obtained by using the function
839 @c   <function>gcry_md_get_algo_dlen</> but in most cases it will be a statically
840 @c   allocated buffer.
841 @c   </para>
842 @c </refentry>
843 @c 
844 @c 
845
846
847 @c **********************************************************
848 @c *******************  Public Key  *************************
849 @c **********************************************************
850 @node Public Key Functions
851 @chapter Public Key Functions
852
853 How to use asymmetric encryption.
854
855 @c <refentry>
856 @c   <refnamediv>
857 @c     <refname>gcry_pk_encrypt</refname>
858 @c     <refpurpose>do a public key encryption</refpurpose>
859 @c   </refnamediv>
860 @c 
861 @c   <refsynopsisdiv>
862 @c     <funcsynopsis>
863 @c       <funcsynopsisinfo>
864 @c       #include &lt;gcrypt.h&gt;
865 @c       </funcsynopsisinfo>
866 @c       <funcprototype>
867 @c         <funcdef>int <function>gcry_pk_encrypt</function></funcdef>
868 @c         <paramdef>GCRY_SEXP *<parameter>result</parameter></paramdef>
869 @c         <paramdef>GCRY_SEXP  <parameter>data</parameter></paramdef>
870 @c         <paramdef>GCRY_SEXP  <parameter>pkey</parameter></paramdef>
871 @c       </funcprototype>
872 @c     </funcsynopsis>
873 @c   </refsynopsisdiv>
874 @c 
875 @c 
876 @c   <refsect1><title>Description</title>
877 @c   <para>
878 @c   <indexterm><primary>public key functions</primary>
879 @c              <secondary>gcry_pk_encrypt</secondary>
880 @c              </indexterm>
881 @c   <function>gcry_pk_encrypt</function> performs public key encryption
882 @c   operations.  The caller has to provide a public key as the &sexp;
883 @c   <parameter>pkey</> and <parameter>data</> as a &sexp;
884 @c   with just one MPI in it.  The function returns a &sexp; which may
885 @c   be passed tp to pk_decrypt.
886 @c   Later versions of this functions may take more complex input data.
887 @c 
888 @c   Returns: 0 or an errorcode.
889 @c   </para>
890 @c   <literallayout>
891 @c   s_data = (<replaceable/mpi/)
892 @c   s_pkey = <replaceable/key-as-defined-in-sexp_to_key/
893 @c   r_ciph = (enc-val
894 @c              (<replaceable/algo/
895 @c                (<replaceable/param_name1/ <replaceable/mpi/)
896 @c                ...
897 @c                (<replaceable/param_namen/ <replaceable/mpi/)
898 @c              ))
899 @c   </literallayout>
900 @c </refentry>
901 @c 
902 @c 
903 @c <!--
904 @c int gcry_pk_decrypt( GCRY_SEXP *result, GCRY_SEXP data, GCRY_SEXP skey );
905 @c 
906 @c 
907 @c 
908 @c int gcry_pk_sign(    GCRY_SEXP *result, GCRY_SEXP data, GCRY_SEXP skey );
909 @c int gcry_pk_verify(  GCRY_SEXP sigval, GCRY_SEXP data, GCRY_SEXP pkey );
910 @c int gcry_pk_testkey( GCRY_SEXP key );
911 @c int gcry_pk_genkey(  GCRY_SEXP *r_key, GCRY_SEXP s_parms );
912 @c 
913 @c int gcry_pk_ctl( int cmd, void *buffer, size_t buflen);
914 @c int gcry_pk_algo_info( int algo, int what, void *buffer, size_t *nbytes);
915 @c #define gcry_pk_test_algo(a) \
916 @c             gcry_pk_algo_info( (a), GCRYCTL_TEST_ALGO, NULL, NULL )
917 @c 
918 @c const char *gcry_pk_algo_name( int algo );
919 @c int gcry_pk_map_name( const char* name );
920 @c unsigned int gcry_pk_get_nbits( GCRY_SEXP key );
921 @c     -->
922 @c 
923
924 @c **********************************************************
925 @c *******************  Random  *****************************
926 @c **********************************************************
927 @node Random Numbers
928 @chapter Random Numbers
929
930
931 @deftypefun void gcry_randomize (unsigned char *@var{buffer}, size_t @var{length}, enum gcry_random_level @var{level})
932
933 Fill @var{buffer} with @var{length} random bytes using a random quality
934 as defined by @var{level}.
935 @end deftypefun
936
937 @deftypefun void *gcry_random_bytes (size_t @var{nbytes}, enum gcry_random_level @var{level})
938
939 Allocate a memory block consisting of @var{nbytes} fresh random bytes
940 using a random quality as defined by @var{level}.
941 @end deftypefun
942
943 @deftypefun void *gcry_random_bytes_secure (size_t @var{nbytes}, enum gcry_random_level @var{level})
944
945 Allocate a memory block consisting of @var{nbytes} fresh random bytes
946 using a random quality as defined by @var{level}.  This function
947 differs from @code{gcry_random_bytes} in that the returned buffer is
948 allcated in a ``secure'' area of the memory.
949 @end deftypefun
950
951
952
953 @c **********************************************************
954 @c *******************  Utilities  **************************
955 @c **********************************************************
956 @node Utilities
957 @chapter Utilities
958
959 Helper functions.
960
961 @c       <funcprototype>
962 @c         <funcdef>int <function>gcry_control</function></funcdef>
963 @c         <paramdef>enum gcry_ctl_cmds<parameter>cmd</parameter></paramdef>
964 @c         <paramdef><parameter>...</parameter></paramdef>
965 @c       </funcprototype>
966 @c     </funcsynopsis>
967 @c   </refsynopsisdiv>
968 @c 
969 @c   <refsect1><title>Description</title>
970 @c   <para>
971 @c   <indexterm><primary>gcry_control</primary></indexterm>
972 @c   This function is used to control various aspects of &libgcrypt;
973 @c   FIXME: Explain all commands here.
974 @c   </para>
975 @c </refentry>
976 @c 
977 @c 
978 @c 
979 @c 
980 @c 
981 @c <refentry>
982 @c   <refnamediv>
983 @c     <refname>gcry_set_allocation_handler</refname>
984 @c     <refname>gcry_set_outofcore_handler</refname>
985 @c         <refpurpose>Use application defined malloc functions</refpurpose>
986 @c   </refnamediv>
987 @c 
988 @c   <refsynopsisdiv>
989 @c     <funcsynopsis>
990 @c       <funcsynopsisinfo>
991 @c       #include &lt;gcrypt.h&gt;
992 @c       </funcsynopsisinfo>
993 @c       <funcprototype>
994 @c         <funcdef>void <function>gcry_set_allocation_handler</></funcdef>
995 @c         <paramdef>void *(*<parameter>alloc_func</>)(size_t n)</paramdef>
996 @c         <paramdef>void *(*<parameter>alloc_secure_func</>)(size_t n)</paramdef>
997 @c         <paramdef>int (*<parameter>is_secure_func</>)(const void *p)</paramdef>
998 @c         <paramdef>void *(*<parameter>realloc_func</>)(void *p, size_t n)</paramdef>
999 @c         <paramdef>void (*<parameter>free_func</>)(void *p)</paramdef>
1000 @c       </funcprototype>
1001 @c       <funcprototype>
1002 @c         <funcdef>void <function>gcry_set_outofcore_handler</></funcdef>
1003 @c 
1004 @c         <paramdef>int (*<parameter>h</>)( void*, size_t, unsigned int ),
1005 @c                                         void *opaque )</paramdef>
1006 @c       </funcprototype>
1007 @c     </funcsynopsis>
1008 @c   </refsynopsisdiv>
1009 @c 
1010 @c   <refsect1><title>Description</title>
1011 @c   <para>
1012 @c   <indexterm><primary>gcry_set_allocation_handler</primary></indexterm>
1013 @c   <indexterm><primary>gcry_set_outofcore_handler</primary></indexterm>
1014 @c 
1015 @c   FIXME
1016 @c   </para>
1017 @c </refentry>
1018 @c 
1019 @c 
1020 @c <refentry>
1021 @c   <refnamediv>
1022 @c     <refname>gcry_set_fatalerror_handler</refname>
1023 @c         <refpurpose>change the default fatal error handler</refpurpose>
1024 @c   </refnamediv>
1025 @c 
1026 @c   <refsynopsisdiv>
1027 @c     <funcsynopsis>
1028 @c       <funcsynopsisinfo>
1029 @c       #include &lt;gcrypt.h&gt;
1030 @c       </funcsynopsisinfo>
1031 @c       <funcprototype>
1032 @c         <funcdef>void <function>gcry_set_fatalerror_handler</></funcdef>
1033 @c         <paramdef>void (*<parameter>func</>)(
1034 @c              void *, int, const char*)</paramdef>
1035 @c         <paramdef>void *<parameter>opaque</></paramdef>
1036 @c       </funcprototype>
1037 @c     </funcsynopsis>
1038 @c   </refsynopsisdiv>
1039 @c 
1040 @c   <refsect1><title>Description</title>
1041 @c   <para>
1042 @c   <indexterm><primary>gcry_set_fatalerror_handler</primary></indexterm>
1043 @c   At certain places the &libgcrypt; may need to call a fatal error fucntion
1044 @c   which does terminate the process.  To allow an application to do
1045 @c   some emergency cleanup, it may register a fatal error handler with
1046 @c   the library.  This handler is assumed to terminate the application;
1047 @c   however if it returns &libgcrypt; will abort anyway.
1048 @c      </para>
1049 @c   <para>
1050 @c The handler is called with the opaque value registered here, an
1051 @c errorcode from &libgcrypt; and some descriptive text string.
1052 @c   </para>
1053 @c </refentry>
1054 @c 
1055 @c 
1056 @c <refentry>
1057 @c   <refnamediv>
1058 @c     <refname>gcry_set_gettext_handler</refname>
1059 @c         <refpurpose>Change the default gettext function</refpurpose>
1060 @c   </refnamediv>
1061 @c 
1062 @c   <refsynopsisdiv>
1063 @c     <funcsynopsis>
1064 @c       <funcsynopsisinfo>
1065 @c       #include &lt;gcrypt.h&gt;
1066 @c       </funcsynopsisinfo>
1067 @c       <funcprototype>
1068 @c         <funcdef>void <function>gcry_set_gettext_handler</></funcdef>
1069 @c         <paramdef>const char *(*<parameter>func</>)(const char*)</paramdef>
1070 @c         <paramdef>void *<parameter>opaque</></paramdef>
1071 @c       </funcprototype>
1072 @c     </funcsynopsis>
1073 @c   </refsynopsisdiv>
1074 @c 
1075 @c   <refsect1><title>Description</title>
1076 @c   <para>
1077 @c   <indexterm><primary>gcry_set_log_handler</primary></indexterm>
1078 @c   FIXME!!
1079 @c   </para>
1080 @c </refentry>
1081 @c 
1082 @c 
1083 @c 
1084 @c <!--
1085 @c void gcry_set_log_handler( void (*f)(void*,int, const char*, va_list ),
1086 @c                                                              void
1087 @c                                                              *opaque
1088 @c                                                              );
1089 @c -->
1090 @c 
1091 @c <refentry>
1092 @c   <refnamediv>
1093 @c     <refname>gcry_set_log_handler</refname>
1094 @c         <refpurpose>Change the default logging function</refpurpose>
1095 @c   </refnamediv>
1096 @c 
1097 @c   <refsynopsisdiv>
1098 @c     <funcsynopsis>
1099 @c       <funcsynopsisinfo>
1100 @c       #include &lt;gcrypt.h&gt;
1101 @c       </funcsynopsisinfo>
1102 @c       <funcprototype>
1103 @c         <funcdef>void <function>gcry_set_log_handler</></funcdef>
1104 @c         <paramdef>void (*<parameter>func</>)
1105 @c          (void*, int, const char*, va_list)</paramdef>
1106 @c         <paramdef>void *<parameter>opaque</></paramdef>
1107 @c       </funcprototype>
1108 @c     </funcsynopsis>
1109 @c   </refsynopsisdiv>
1110 @c 
1111 @c   <refsect1><title>Description</title>
1112 @c   <para>
1113 @c   <indexterm><primary>gcry_set_log_handler</primary></indexterm>
1114 @c   &libgcrypt; has it;s own logging functions.  Applications which 
1115 @c   need to use their own, should provide a log function to &libgcrypt;
1116 @c so that it will use this function instead.
1117 @c 
1118 @c Fixme: Describe how this is intended to work.
1119 @c   </para>
1120 @c </refentry>
1121 @c 
1122 @c <!--
1123 @c void *gcry_malloc( size_t n );
1124 @c void *gcry_calloc( size_t n, size_t m );
1125 @c void *gcry_malloc_secure( size_t n );
1126 @c void *gcry_calloc_secure( size_t n, size_t m );
1127 @c void *gcry_realloc( void *a, size_t n );
1128 @c void *gcry_xmalloc( size_t n );
1129 @c void *gcry_xcalloc( size_t n, size_t m );
1130 @c void *gcry_xmalloc_secure( size_t n );
1131 @c void *gcry_xcalloc_secure( size_t n, size_t m );
1132 @c void *gcry_xrealloc( void *a, size_t n );
1133 @c char *gcry_xstrdup( const char * a);
1134 @c void  gcry_free( void *a );
1135 @c int   gcry_is_secure( const void *a );
1136 @c -->
1137 @c 
1138 @c <refentry>
1139 @c   <refnamediv>
1140 @c     <refname>gcry_malloc</refname>
1141 @c     <refname>gcry_calloc</refname>
1142 @c     <refname>gcry_malloc_secure</refname>
1143 @c     <refname>gcry_calloc_secure</refname>
1144 @c     <refname>gcry_realloc</refname>
1145 @c     <refname>gcry_xmalloc</refname>
1146 @c     <refname>gcry_xcalloc</refname>
1147 @c     <refname>gcry_xmalloc_secure</refname>
1148 @c     <refname>gcry_xcalloc_secure</refname>
1149 @c     <refname>gcry_xrealloc</refname>
1150 @c     <refname>gcry_xstrdup</refname>
1151 @c 
1152 @c  <!-- WORk WORK -->
1153 @c     <refname>gcry_malloc</refname>
1154 @c     <refname>gcry_malloc</refname>
1155 @c     
1156 @c         <refpurpose>Change the default logging function</refpurpose>
1157 @c   </refnamediv>
1158 @c 
1159 @c   <refsynopsisdiv>
1160 @c     <funcsynopsis>
1161 @c       <funcsynopsisinfo>
1162 @c       #include &lt;gcrypt.h&gt;
1163 @c       </funcsynopsisinfo>
1164 @c       <funcprototype>
1165 @c         <funcdef>void <function>gcry_set_log_handler</></funcdef>
1166 @c         <paramdef>void (*<parameter>func</>)
1167 @c          (void*, int, const char*, va_list)</paramdef>
1168 @c         <paramdef>void *<parameter>opaque</></paramdef>
1169 @c       </funcprototype>
1170 @c     </funcsynopsis>
1171 @c   </refsynopsisdiv>
1172 @c 
1173 @c   <refsect1><title>Description</title>
1174 @c   <para>
1175 @c   <indexterm><primary>gcry_set_log_handler</primary></indexterm>
1176 @c   &libgcrypt; has it;s own logging functions.  Applications which 
1177 @c   need to use their own, should provide a log function to &libgcrypt;
1178 @c so that it will use this function instead.
1179 @c 
1180 @c Fixme: Describe how this is intended to work.
1181 @c   </para>
1182 @c </refentry>
1183 @c 
1184 @c 
1185
1186
1187 @c **********************************************************
1188 @c *******************  Errors  ****************************
1189 @c **********************************************************
1190 @node Error Handling
1191 @chapter Error Handling
1192
1193 Most functions in `Libgcrypt' are returning an error if they fail.  For
1194 this reason, the application should always catch the error condition and
1195 take appropriate measures, for example by releasing the resources and
1196 passing the error up to the caller, or by displaying a descriptive
1197 message to the user and cancelling the operation.
1198
1199 Some error values do not indicate a system error or an error in the
1200 operation, but the result of an operation that failed properly.
1201
1202 @menu
1203 * Error values::                A list of all error values used.
1204 * Error strings::               How to get a descriptive string from a value.
1205 @end menu
1206
1207 @node Error values
1208 @section Error values
1209
1210 Errors are return as an @code{int} 
1211 Except for the EOF and No_Error cases an application should always
1212 use the constants.  Possible values are:
1213
1214 @table @code
1215 @item GCRYERR_EOF
1216 This value indicates the end of a list, buffer or file and is defined to have
1217 the value @code{-1}.
1218
1219 @item GCRYERR_SUCCESS
1220 This value indicates success.  The value of this error is @code{0}.
1221
1222 @item GCRYERR_GENERAL
1223 This value means that something went wrong, but either there is not
1224 enough information about the problem to return a more useful error
1225 value, or there is no seperate error value for this type of problem.
1226
1227 @end table
1228
1229
1230 @node Error strings
1231 @section Error strings
1232
1233 @deftypefun {const char *} gcry_strerror (@w{int @var{err}})
1234 The function @code{gcry_strerror} returns a pointer to a statically
1235 allocated string containing a description of the error with the error
1236 value @var{err}.  This string can be used to output a diagnostic
1237 message to the user.
1238 @end deftypefun
1239
1240
1241
1242
1243 @c **********************************************************
1244 @c *******************  Appendices  *************************
1245 @c **********************************************************
1246
1247 @include lgpl.texi
1248
1249 @include gpl.texi
1250
1251 @include fdl.texi
1252
1253 @node Concept Index
1254 @unnumbered Concept Index
1255
1256 @printindex cp
1257
1258 @node Function and Data Index
1259 @unnumbered Function and Data Index
1260
1261 @printindex fn
1262
1263 @summarycontents
1264 @contents
1265 @bye
1266