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