* cipher.c (gcry_cipher_open): Don't reject CTS flag.
[libgcrypt.git] / doc / misc-ref.sgml
1 <!-- misc-ref.sgml - libgcrypt reference (digests)
2     Copyright (C) 2000 Free Software Foundation, Inc.
3
4     This file is part of libgcrypt.
5
6     libgcrypt is free software; you can redistribute it and/or modify
7     it under the terms of the GNU General Public License as published by
8     the Free Software Foundation; either version 2 of the License, or
9     (at your option) any later version.
10
11     libgcrypt is distributed in the hope that it will be useful,
12     but WITHOUT ANY WARRANTY; without even the implied warranty of
13     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14     GNU General Public License for more details.
15
16     You should have received a copy of the GNU General Public License
17     along with this program; if not, write to the Free Software
18     Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
19 -->
20
21 <refentry>
22   <refnamediv>
23     <refname>gcry_check_version</refname>
24     <refpurpose>get or check the version of libgcrypt</refpurpose>
25   </refnamediv>
26
27   <refsynopsisdiv>
28     <funcsynopsis>
29       <funcsynopsisinfo>
30       #include &lt;gcrypt.h&gt;
31       </funcsynopsisinfo>
32       <funcprototype>
33         <funcdef>const char *<function>gcry_check_version</function></funcdef>
34         <paramdef>const char *<parameter>req_version</parameter></paramdef>
35       </funcprototype>
36     </funcsynopsis>
37   </refsynopsisdiv>
38
39   <refsect1><title>Description</title>
40   <para>
41   <indexterm><primary>gcry_check_version</primary>
42              </indexterm>
43   <function>gcry_check_version</function> checks
44 that the version of the library is at minimum the requested one
45 and return the version string; NULL is returned if the condition is
46 not met.  You may pass NULL as reqy_version to simply get the version
47 string back without any checking.
48   </para>
49 </refentry>
50
51 <refentry>
52   <refnamediv>
53     <refname>gcry_errno</refname>
54     <refname>gcry_strerror</refname>
55     <refpurpose>Get the last error</refpurpose>
56   </refnamediv>
57
58   <refsynopsisdiv>
59     <funcsynopsis>
60       <funcsynopsisinfo>
61       #include &lt;gcrypt.h&gt;
62       </funcsynopsisinfo>
63       <funcprototype>
64         <funcdef>int <function>gcry_errno</function></funcdef>
65         <paramdef></paramdef>
66       </funcprototype>
67       <funcprototype>
68         <funcdef>const char *<function>gcry_strerror</function></funcdef>
69         <paramdef>int<parameter>no</parameter></paramdef>
70       </funcprototype>
71     </funcsynopsis>
72   </refsynopsisdiv>
73
74   <refsect1><title>Description</title>
75   <para>
76   <indexterm><primary>gcry_errno</primary></indexterm>
77   <indexterm><primary>gcry_strerror</primary></indexterm>
78   Both function are to be used like there Standard-C
79   counterparts.  However <function>gcry_errno</function> is a function
80   and not just a global variable.  If -1 is passed to
81   <function>gcry_strerror</>, <function>gcry_errno</> is implictly used.
82   </para>
83 </refentry>
84
85
86 <refentry>
87   <refnamediv>
88     <refname>gcry_control</refname>
89         <refpurpose>Multi purpose control function</refpurpose>
90   </refnamediv>
91
92   <refsynopsisdiv>
93     <funcsynopsis>
94       <funcsynopsisinfo>
95       #include &lt;gcrypt.h&gt;
96       </funcsynopsisinfo>
97       <funcprototype>
98         <funcdef>int <function>gcry_control</function></funcdef>
99         <paramdef>enum gcry_ctl_cmds<parameter>cmd</parameter></paramdef>
100         <paramdef><parameter>...</parameter></paramdef>
101       </funcprototype>
102     </funcsynopsis>
103   </refsynopsisdiv>
104
105   <refsect1><title>Description</title>
106   <para>
107   <indexterm><primary>gcry_control</primary></indexterm>
108   This function is used to control various aspects of &libgcrypt;
109   FIXME: Explain all commands here.
110   </para>
111 </refentry>
112
113
114
115
116
117 <refentry>
118   <refnamediv>
119     <refname>gcry_set_allocation_handler</refname>
120     <refname>gcry_set_outofcore_handler</refname>
121         <refpurpose>Use application defined malloc functions</refpurpose>
122   </refnamediv>
123
124   <refsynopsisdiv>
125     <funcsynopsis>
126       <funcsynopsisinfo>
127       #include &lt;gcrypt.h&gt;
128       </funcsynopsisinfo>
129       <funcprototype>
130         <funcdef>void <function>gcry_set_allocation_handler</></funcdef>
131         <paramdef>void *(*<parameter>alloc_func</>)(size_t n)</paramdef>
132         <paramdef>void *(*<parameter>alloc_secure_func</>)(size_t n)</paramdef>
133         <paramdef>int (*<parameter>is_secure_func</>)(const void *p)</paramdef>
134         <paramdef>void *(*<parameter>realloc_func</>)(void *p, size_t n)</paramdef>
135         <paramdef>void (*<parameter>free_func</>)(void *p)</paramdef>
136       </funcprototype>
137       <funcprototype>
138         <funcdef>void <function>gcry_set_outofcore_handler</></funcdef>
139
140         <paramdef>int (*<parameter>h</>)( void*, size_t, unsigned int ),
141                                         void *opaque )</paramdef>
142       </funcprototype>
143     </funcsynopsis>
144   </refsynopsisdiv>
145
146   <refsect1><title>Description</title>
147   <para>
148   <indexterm><primary>gcry_set_allocation_handler</primary></indexterm>
149   <indexterm><primary>gcry_set_outofcore_handler</primary></indexterm>
150
151   FIXME
152   </para>
153 </refentry>
154
155
156 <refentry>
157   <refnamediv>
158     <refname>gcry_set_fatalerror_handler</refname>
159         <refpurpose>change the default fatal error handler</refpurpose>
160   </refnamediv>
161
162   <refsynopsisdiv>
163     <funcsynopsis>
164       <funcsynopsisinfo>
165       #include &lt;gcrypt.h&gt;
166       </funcsynopsisinfo>
167       <funcprototype>
168         <funcdef>void <function>gcry_set_fatalerror_handler</></funcdef>
169         <paramdef>void (*<parameter>func</>)(
170              void *, int, const char*)</paramdef>
171         <paramdef>void *<parameter>opaque</></paramdef>
172       </funcprototype>
173     </funcsynopsis>
174   </refsynopsisdiv>
175
176   <refsect1><title>Description</title>
177   <para>
178   <indexterm><primary>gcry_set_fatalerror_handler</primary></indexterm>
179   At certain places the &libgcrypt; may need to call a fatal error fucntion
180   which does terminate the process.  To allow an application to do
181   some emergency cleanup, it may register a fatal error handler with
182   the library.  This handler is assumed to terminate the application;
183   however if it returns &libgcrypt; will abort anyway.
184      </para>
185   <para>
186 The handler is called with the opaque value registered here, an
187 errorcode from &libgcrypt; and some descriptive text string.
188   </para>
189 </refentry>
190
191
192 <refentry>
193   <refnamediv>
194     <refname>gcry_set_gettext_handler</refname>
195         <refpurpose>Change the default gettext function</refpurpose>
196   </refnamediv>
197
198   <refsynopsisdiv>
199     <funcsynopsis>
200       <funcsynopsisinfo>
201       #include &lt;gcrypt.h&gt;
202       </funcsynopsisinfo>
203       <funcprototype>
204         <funcdef>void <function>gcry_set_gettext_handler</></funcdef>
205         <paramdef>const char *(*<parameter>func</>)(const char*)</paramdef>
206         <paramdef>void *<parameter>opaque</></paramdef>
207       </funcprototype>
208     </funcsynopsis>
209   </refsynopsisdiv>
210
211   <refsect1><title>Description</title>
212   <para>
213   <indexterm><primary>gcry_set_log_handler</primary></indexterm>
214   FIXME!!
215   </para>
216 </refentry>
217
218
219
220 <!--
221 void gcry_set_log_handler( void (*f)(void*,int, const char*, va_list ),
222                                                              void
223                                                              *opaque
224                                                              );
225 -->
226
227 <refentry>
228   <refnamediv>
229     <refname>gcry_set_log_handler</refname>
230         <refpurpose>Change the default logging function</refpurpose>
231   </refnamediv>
232
233   <refsynopsisdiv>
234     <funcsynopsis>
235       <funcsynopsisinfo>
236       #include &lt;gcrypt.h&gt;
237       </funcsynopsisinfo>
238       <funcprototype>
239         <funcdef>void <function>gcry_set_log_handler</></funcdef>
240         <paramdef>void (*<parameter>func</>)
241          (void*, int, const char*, va_list)</paramdef>
242         <paramdef>void *<parameter>opaque</></paramdef>
243       </funcprototype>
244     </funcsynopsis>
245   </refsynopsisdiv>
246
247   <refsect1><title>Description</title>
248   <para>
249   <indexterm><primary>gcry_set_log_handler</primary></indexterm>
250   &libgcrypt; has it;s own logging functions.  Applications which 
251   need to use their own, should provide a log function to &libgcrypt;
252 so that it will use this function instead.
253
254 Fixme: Describe how this is intended to work.
255   </para>
256 </refentry>
257
258 <!--
259 void *gcry_malloc( size_t n );
260 void *gcry_calloc( size_t n, size_t m );
261 void *gcry_malloc_secure( size_t n );
262 void *gcry_calloc_secure( size_t n, size_t m );
263 void *gcry_realloc( void *a, size_t n );
264 void *gcry_xmalloc( size_t n );
265 void *gcry_xcalloc( size_t n, size_t m );
266 void *gcry_xmalloc_secure( size_t n );
267 void *gcry_xcalloc_secure( size_t n, size_t m );
268 void *gcry_xrealloc( void *a, size_t n );
269 char *gcry_xstrdup( const char * a);
270 void  gcry_free( void *a );
271 int   gcry_is_secure( const void *a );
272 -->
273
274 <refentry>
275   <refnamediv>
276     <refname>gcry_malloc</refname>
277     <refname>gcry_calloc</refname>
278     <refname>gcry_malloc_secure</refname>
279     <refname>gcry_calloc_secure</refname>
280     <refname>gcry_realloc</refname>
281     <refname>gcry_xmalloc</refname>
282     <refname>gcry_xcalloc</refname>
283     <refname>gcry_xmalloc_secure</refname>
284     <refname>gcry_xcalloc_secure</refname>
285     <refname>gcry_xrealloc</refname>
286     <refname>gcry_xstrdup</refname>
287
288  <!-- WORk WORK -->
289     <refname>gcry_malloc</refname>
290     <refname>gcry_malloc</refname>
291     
292         <refpurpose>Change the default logging function</refpurpose>
293   </refnamediv>
294
295   <refsynopsisdiv>
296     <funcsynopsis>
297       <funcsynopsisinfo>
298       #include &lt;gcrypt.h&gt;
299       </funcsynopsisinfo>
300       <funcprototype>
301         <funcdef>void <function>gcry_set_log_handler</></funcdef>
302         <paramdef>void (*<parameter>func</>)
303          (void*, int, const char*, va_list)</paramdef>
304         <paramdef>void *<parameter>opaque</></paramdef>
305       </funcprototype>
306     </funcsynopsis>
307   </refsynopsisdiv>
308
309   <refsect1><title>Description</title>
310   <para>
311   <indexterm><primary>gcry_set_log_handler</primary></indexterm>
312   &libgcrypt; has it;s own logging functions.  Applications which 
313   need to use their own, should provide a log function to &libgcrypt;
314 so that it will use this function instead.
315
316 Fixme: Describe how this is intended to work.
317   </para>
318 </refentry>
319
320
321 <!--
322 void gcry_randomize( byte *buffer, size_t length,
323                      enum gcry_random_level level );
324 void *gcry_random_bytes( size_t nbytes, enum gcry_random_level level );
325 void *gcry_random_bytes_secure( size_t nbytes, enum gcry_random_level level );
326
327     -->
328
329
330
331
332
333