3b4dcd7e88f2fc591a71881b7ccca5c3ca2b598a
[gnupg.git] / doc / gcryptref-digest.sgml
1 <!-- gcryptref-digest.sgml - libgcrypt reference (digests)
2     Copyright (C) 2000 Free Software Foundation, Inc.
3
4     This file is part of GnuPG.
5
6     GnuPG 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     GnuPG 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 <!--**********************************************
22 ***********  md_open, close, enable  ************
23 ***********************************************-->
24 <refentry>
25   <refnamediv>
26     <refname>gcry_md_open</refname>
27     <refname>gcry_md_enable</refname>
28     <refname>gcry_md_close</refname>
29     <refpurpose>create and destroy a message digest context</refpurpose>
30   </refnamediv>
31
32   <refsynopsisdiv>
33     <funcsynopsis>
34       <funcsynopsisinfo>
35       #include &lt;gcrypt.h&gt;
36       </funcsynopsisinfo>
37       <funcprototype>
38         <funcdef>GCRY_MD_HD <function>gcry_md_open</function></funcdef>
39         <paramdef>int <parameter>algo</parameter></paramdef>
40         <paramdef>unsigned int <parameter>flags</parameter></paramdef>
41       </funcprototype>
42       <funcprototype>
43         <funcdef>void <function>gcry_md_enable</function></funcdef>
44         <paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
45         <paramdef>int <parameter>algo</parameter></paramdef>
46       </funcprototype>
47       <funcprototype>
48         <funcdef>void <function>gcry_md_close</function></funcdef>
49         <paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
50       </funcprototype>
51     </funcsynopsis>
52   </refsynopsisdiv>
53
54
55   <refsect1><title>Description</title>
56   <para>
57   <indexterm><primary>hash functions</primary>
58              <secondary>gcry_md_open</secondary>
59              </indexterm>
60   <indexterm><primary>hash functions</primary>
61              <secondary>gcry_md_enable</secondary>
62              </indexterm>
63   <indexterm><primary>hash functions</primary>
64              <secondary>gcry_md_close</secondary>
65              </indexterm>
66   <function>gcry_md_open</function> creates the context required for
67   the message digest functions.  The hash algorithm may optionally be
68   specified. It is possible to use these functions as MAC functons; therefore
69   the flag <literal/GCRY_MD_FLAG_HMAC/ must be given along with the
70   hash functions.  Other MAC algorithms than  HMAC are currently not
71   supported.  The key for the MAC must be set using
72   the <function>gcry_md_setkey</> function.
73   <function>gcry_md_close</function> releases all resources associated
74   with the context.
75   <function>gcry_md_enable</function> may be used to enable hash
76   algorithms.  This function may be used multiple times to create
77   a hash context for multiple algorithms.  Adding an already enabled algorithm
78   has no effect.  A algorithm must be enabled prios to calculate hash
79   algorithms.
80   </para>
81 </refentry>
82
83 <!--**********************************************
84 ***********  md_copy *****************************
85 ***********************************************-->
86 <refentry>
87   <refnamediv>
88     <refname>gcry_md_copy</refname>
89     <refpurpose>create and copy of a message digest context</refpurpose>
90   </refnamediv>
91
92   <refsynopsisdiv>
93     <funcsynopsis>
94       <funcsynopsisinfo>
95       #include &lt;gcrypt.h&gt;
96       </funcsynopsisinfo>
97       <funcprototype>
98         <funcdef>GCRY_MD_HD <function>gcry_md_copy</function></funcdef>
99         <paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
100       </funcprototype>
101     </funcsynopsis>
102   </refsynopsisdiv>
103
104
105   <refsect1><title>Description</title>
106   <para>
107   <indexterm><primary>hash functions</primary>
108              <secondary>gcry_md_copy</secondary>
109              </indexterm>
110   <function>gcry_md_copy</function> creates an excat copy of the given context.
111   This is useful to calculate hashes with a common initial part of the
112   plaintext.
113   </para>
114 </refentry>
115
116 <!--**********************************************
117 ***********  md_reset  ***************************
118 ***********************************************-->
119 <refentry>
120   <refnamediv>
121     <refname>gcry_md_reset</refname>
122     <refpurpose>reset a message digest context</refpurpose>
123   </refnamediv>
124
125   <refsynopsisdiv>
126     <funcsynopsis>
127       <funcsynopsisinfo>
128       #include &lt;gcrypt.h&gt;
129       </funcsynopsisinfo>
130       <funcprototype>
131         <funcdef>void <function>gcry_md_reset</function></funcdef>
132         <paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
133       </funcprototype>
134     </funcsynopsis>
135   </refsynopsisdiv>
136
137
138   <refsect1><title>Description</title>
139   <para>
140   <indexterm><primary>hash functions</primary>
141              <secondary>gcry_md_reset</secondary>
142              </indexterm>
143   <function>gcry_md_reset</function> is used to reuse a message context
144   without the overhead of an open and close operation.
145   </para>
146 </refentry>
147
148
149 <!--**********************************************
150 ***********  md_ctl  *****************************
151 ***********************************************-->
152 <refentry>
153   <refnamediv>
154     <refname>gcry_md_ctl</refname>
155     <refname>gcry_md_final</refname>
156     <refname>gcry_md_setkey</refname>
157     <refpurpose>perform special operations on a digest context</refpurpose>
158   </refnamediv>
159
160   <refsynopsisdiv>
161     <funcsynopsis>
162       <funcsynopsisinfo>
163       #include &lt;gcrypt.h&gt;
164       </funcsynopsisinfo>
165       <funcprototype>
166         <funcdef>int <function>gcry_md_ctl</function></funcdef>
167         <paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
168         <paramdef>int <parameter>cmd</parameter></paramdef>
169         <paramdef>unsigned char * <parameter>buffer</parameter></paramdef>
170         <paramdef>size_t <parameter>buflen</parameter></paramdef>
171       </funcprototype>
172     </funcsynopsis>
173   </refsynopsisdiv>
174
175
176   <refsect1><title>Description</title>
177   <para>
178   <indexterm><primary>hash functions</primary>
179              <secondary>gcry_md_ctl</secondary>
180              </indexterm>
181   <function>gcry_md_ctl</function> is a multi-purpose function
182   to control the behaviour of all gcry_md functions or one instance
183   of it.
184   </para>
185   <para>
186   Currently defined values for <parameter>cmd</> are:
187   </para>
188   <para>
189     <literal>GCRYCTL_FINALIZE</> and the convenience macro
190     <function>gcry_md_final(a)</>
191   </para>
192   <para>
193     <literal>GCRYCTL_SET_KEY</> and the convenience macro
194     <function>gcry_md_setkey(a)</>.  This is used to turn these
195     hash functions into MAC functions.  The key may be any string
196     of the speicified length.  The type of the MAC is determined
197     by special flags set with the open function.
198     NEW:  There is now a function to do this
199   </para>
200 </refentry>
201
202 <!--**********************************************
203 ***********  md_write, putc  *********************
204 ***********************************************-->
205 <refentry>
206   <refnamediv>
207     <refname>gcry_md_write</refname>
208     <refname>gcry_md_putc</refname>
209     <refpurpose>calculate the message digest of a buffer</refpurpose>
210   </refnamediv>
211
212   <refsynopsisdiv>
213     <funcsynopsis>
214       <funcsynopsisinfo>
215       #include &lt;gcrypt.h&gt;
216       </funcsynopsisinfo>
217       <funcprototype>
218         <funcdef>int <function>gcry_md_write</function></funcdef>
219         <paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
220         <paramdef>unsigned char * <parameter>buffer</parameter></paramdef>
221         <paramdef>size_t <parameter>buflen</parameter></paramdef>
222       </funcprototype>
223       <funcprototype>
224         <funcdef>int <function>gcry_md_putc</function></funcdef>
225         <paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
226         <paramdef>int <parameter>c</parameter></paramdef>
227       </funcprototype>
228     </funcsynopsis>
229   </refsynopsisdiv>
230
231
232   <refsect1><title>Description</title>
233   <para>
234   <indexterm><primary>hash functions</primary>
235              <secondary>gcry_md_write</secondary></indexterm>
236   <indexterm><primary>hash functions</primary>
237              <secondary>gcry_md_putc</secondary></indexterm>
238   <function>gcry_md_write</function> is used to actually calulate the message
239   digest of a buffer.  This function updates the internal state of the message
240   digest.
241   </para>
242   <para>
243   <function>gcry_md_putc</function> is a macro which is used to update
244   the message digest by one byte.  this is the preferred way to calculate
245   a digest if only a few bytes at a time are available.
246   </para>
247 </refentry>
248
249 <!--**********************************************
250 ***********  md_read *****************************
251 ***********************************************-->
252 <refentry>
253   <refnamediv>
254     <refname>gcry_md_read</refname>
255     <refpurpose>read out the message digest</refpurpose>
256   </refnamediv>
257
258   <refsynopsisdiv>
259     <funcsynopsis>
260       <funcsynopsisinfo>
261       #include &lt;gcrypt.h&gt;
262       </funcsynopsisinfo>
263       <funcprototype>
264         <funcdef>unsigned char * <function>gcry_md_read</function></funcdef>
265         <paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
266         <paramdef>int <parameter>algo</parameter></paramdef>
267       </funcprototype>
268     </funcsynopsis>
269   </refsynopsisdiv>
270
271
272   <refsect1><title>Description</title>
273   <para>
274   <indexterm><primary>hash functions</primary>
275              <secondary>gcry_md_read</secondary>
276              </indexterm>
277   <indexterm><primary>hash functions</primary>
278              <secondary>gcry_md_putc</secondary>
279              </indexterm>
280   <function>gcry_md_read</function> returns the message digest after finalizing
281   the calculation.  This function may be used as often as required but it
282   will alwas return the same value for one handle.  The returned message
283   digest is allocated within the message context and therefore valid until
284   the conext is released.  <parameter>algo</> may be given as 0 to return the
285   only enbaled message digest or it may specify one of the enabled algorithms.
286   The function will return NULL if the algorithm has not been enabled.
287   </para>
288 </refentry>
289
290
291 <!--**********************************************
292 ***********  md_info  ****************************
293 ***********************************************-->
294 <refentry>
295   <refnamediv>
296     <refname>gcry_md_info</refname>
297     <refpurpose>get information about a handle</refpurpose>
298   </refnamediv>
299
300   <refsynopsisdiv>
301     <funcsynopsis>
302       <funcsynopsisinfo>
303       #include &lt;gcrypt.h&gt;
304       </funcsynopsisinfo>
305       <funcprototype>
306         <funcdef>int <function>gcry_md_info</function></funcdef>
307         <paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
308         <paramdef>int        <parameter>what</parameter></paramdef>
309         <paramdef>void * <parameter>buffer</parameter></paramdef>
310         <paramdef>size_t <parameter>buflen</parameter></paramdef>
311       </funcprototype>
312     </funcsynopsis>
313   </refsynopsisdiv>
314
315   <refsect1><title>Description</title>
316   <para>
317   <indexterm><primary>hash functions</primary>
318              <secondary>gcry_md_info</secondary>
319              </indexterm>
320   <function>gcry_md_info</function> returns some information about the
321   handle or an global parameter.
322   </para>
323   <para>
324   The only defined value for <parameter>what</> is
325   <literal>GCRYCTL_IS_SECURE</literal> to return whether the handle
326   has been allocated in secure memory.  Buffer and buflen are not needed
327   in this cases.  The convenience macro <function>gcry_md_is_secure(a)</>
328   may be also used for this purpose.
329   </para>
330 </refentry>
331
332
333 <!--**********************************************
334 ***********  md_algo_info  ***********************
335 ***********************************************-->
336 <refentry>
337   <refnamediv>
338     <refname>gcry_md_algo_info</refname>
339     <refname>gcry_md_test_algo</refname>
340     <refname>gcry_md_get_algo_dlen</refname>
341     <refpurpose>get information about an algorithm</refpurpose>
342   </refnamediv>
343
344   <refsynopsisdiv>
345     <funcsynopsis>
346       <funcsynopsisinfo>
347       #include &lt;gcrypt.h&gt;
348       </funcsynopsisinfo>
349       <funcprototype>
350         <funcdef>int <function>gcry_md_algo_info</function></funcdef>
351         <paramdef>int        <parameter>algo</parameter></paramdef>
352         <paramdef>int        <parameter>what</parameter></paramdef>
353         <paramdef>void * <parameter>buffer</parameter></paramdef>
354         <paramdef>size_t <parameter>buflen</parameter></paramdef>
355       </funcprototype>
356       <funcprototype>
357         <funcdef>unsigned int <function>gcry_md_get_algo_dlen</function></funcdef>
358         <paramdef>int <parameter>algo</parameter></paramdef>
359       </funcprototype>
360     </funcsynopsis>
361   </refsynopsisdiv>
362
363   <refsect1><title>Description</title>
364   <para>
365   <indexterm><primary>hash functions</primary>
366              <secondary>gcry_md_algo_info</secondary>
367              </indexterm>
368   <function>gcry_md_algo_info</function> returns some information about an
369   algorithm.  On error the value -1 is return and a more detailed error
370   description is available with <function>gcry_errno</>.
371   </para>
372   <para>
373   The defined values for <parameter>what</> are
374   <literal>GCRYCTL_TEST_ALGO</literal> to return whether the algorithm
375   is supported. Buffer and buflen are not needed
376   in this cases.  The convenience macro <function>gcry_md_test_algo(a)</>
377   may be used for this purpose.
378   </para>
379   <para>
380   <literal>GCRYCTL_GET_ASNOID</literal> to return whether the ASN.1
381   object identifier.  IF buffer is specified as NULL, only the required
382   length for the buffer is returned.
383   </para>
384   <para>
385   <indexterm><primary>hash functions</primary>
386              <secondary>gcry_md_get_algo_dlen</secondary>
387              </indexterm>
388   <function>gcry_md_get_algo_dlen</function> returns the length of the
389   digest for a given algorithm in bytes.
390   </para>
391 </refentry>
392
393
394 <!--**********************************************
395 ***********  md_algo_name, map_name  *************
396 ***********************************************-->
397 <refentry>
398   <refnamediv>
399     <refname>gcry_md_algo_name</refname>
400     <refname>gcry_md_map_name</refname>
401     <refpurpose>map algorithm to string</refpurpose>
402   </refnamediv>
403
404   <refsynopsisdiv>
405     <funcsynopsis>
406       <funcsynopsisinfo>
407       #include &lt;gcrypt.h&gt;
408       </funcsynopsisinfo>
409       <funcprototype>
410         <funcdef>const char * <function>gcry_md_algo_name</function></funcdef>
411         <paramdef>int        <parameter>algo</parameter></paramdef>
412       </funcprototype>
413       <funcprototype>
414         <funcdef>int <function>gcry_md_map_name</function></funcdef>
415         <paramdef>const char*<parameter>name</parameter></paramdef>
416       </funcprototype>
417     </funcsynopsis>
418   </refsynopsisdiv>
419
420   <refsect1><title>Description</title>
421   <para>
422   <indexterm><primary>hash functions</primary>
423              <secondary>gcry_md_algo_name</secondary>
424              </indexterm>
425   <indexterm><primary>hash functions</primary>
426              <secondary>gcry_md_map_name</secondary>
427              </indexterm>
428   These both functions are used to map a string with the algorithm name to
429   the internal algorithm identifier value and vice versa.
430   </para>
431   <para>
432   <function>gcry_md_algo_name</> never returns NULL even in cases where the
433   algorithm string is not available.  Instead a string consisting of a
434   single question mark is returned.  Do not use this function to test
435   for the existence of an algorithm.
436   </para>
437   <para>
438   <function>gcry_md_map_name</> returns 0 if the algorithm is not known
439   to &libgcrypt;.
440   </para>
441 </refentry>
442
443
444
445 <!--**********************************************
446 ***********  md_hash_buffer  *********************
447 ***********************************************-->
448 <refentry>
449   <refnamediv>
450     <refname>gcry_md_hash_buffer</refname>
451     <refpurpose>fast message calculation</refpurpose>
452   </refnamediv>
453
454   <refsynopsisdiv>
455     <funcsynopsis>
456       <funcsynopsisinfo>
457       #include &lt;gcrypt.h&gt;
458       </funcsynopsisinfo>
459       <funcprototype>
460         <funcdef>int <function>gcry_md_hash_buffer</function></funcdef>
461         <paramdef>int  <parameter>algo</parameter></paramdef>
462         <paramdef>char * <parameter>digest</parameter></paramdef>
463         <paramdef>const char * <parameter>buffer</parameter></paramdef>
464         <paramdef>size_t <parameter>buflen</parameter></paramdef>
465       </funcprototype>
466     </funcsynopsis>
467   </refsynopsisdiv>
468
469   <refsect1><title>Description</title>
470   <para>
471   <indexterm><primary>hash functions</primary>
472              <secondary>gcry_md_hash_buffer</secondary>
473              </indexterm>
474   <function>gcry_md_hash_buffer</function> is a shortcut function
475   to calculate a message digest of a buffer.  This function does not require
476   a context and immediatley returns the message digest.
477   <parameter>digest</> must be string large enough to hold the digest
478   given by algo.  This length may be obtained by using the function
479   <function>gcry_md_get_algo_dlen</> but in most cases it will be a statically
480   allocated buffer.
481   </para>
482 </refentry>
483
484
485 <!-- FIXME: doc gcry_md_setkey */
486