Add some libgcrypt dox
[gnupg.git] / doc / gcryptref-cipher.sgml
1 <!-- gcryptref-cipher.sgml - libgcrypt reference (ciphers)
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 ***********  cipher open, close  *****************
23 ***********************************************-->
24 <refentry>
25   <refnamediv>
26     <refname>gcry_cipher_open</refname>
27     <refname>gcry_cipher_close</refname>
28     <refpurpose>create and destroy an encryption context</refpurpose>
29   </refnamediv>
30
31   <refsynopsisdiv>
32     <funcsynopsis>
33       <funcsynopsisinfo>
34       #include &lt;gcrypt.h&gt;
35       </funcsynopsisinfo>
36       <funcprototype>
37         <funcdef>GCRY_CIPHER_HD <function>gcry_cipher_open</function></funcdef>
38         <paramdef>int <parameter>algo</parameter></paramdef>
39         <paramdef>int <parameter>mode</parameter></paramdef>
40         <paramdef>unsigned in <parameter>flags</parameter></paramdef>
41       </funcprototype>
42       <funcprototype>
43         <funcdef>void <function>gcry_cipher_close</function></funcdef>
44         <paramdef>GCRY_CIPHER_HD <parameter>h</parameter></paramdef>
45       </funcprototype>
46     </funcsynopsis>
47   </refsynopsisdiv>
48
49
50   <refsect1><title>Description</title>
51   <para>
52   <indexterm><primary>cipher functions</primary>
53              <secondary>gcry_cipher_open</secondary>
54              </indexterm>
55   <indexterm><primary>cipher functions</primary>
56              <secondary>gcry_cipher_close</secondary>
57              </indexterm>
58   <function>gcry_cipher_open</function> creates the context required for
59   most of the cipher functions.
60   </para>
61 </refentry>
62
63
64 <!--**********************************************
65 ***********  cipher control  *********************
66 ***********************************************-->
67 <refentry>
68   <refnamediv>
69     <refname>gcry_cipher_ctl</refname>
70     <refname>gcry_cipher_setkey</refname>
71     <refname>gcry_cipher_setiv</refname>
72     <refname>gcry_cipher_setiv</refname>
73     <refpurpose>control cipher functions</refpurpose>
74   </refnamediv>
75
76   <refsynopsisdiv>
77     <funcsynopsis>
78       <funcsynopsisinfo>
79       #include &lt;gcrypt.h&gt;
80       </funcsynopsisinfo>
81       <funcprototype>
82         <funcdef>int <function>gcry_cipher_ctl</function></funcdef>
83         <paramdef>GCRY_CIPHER_HD <parameter>h</parameter></paramdef>
84         <paramdef>int <parameter>cmd</parameter></paramdef>
85         <paramdef>void *<parameter>buffer</parameter></paramdef>
86         <paramdef>size_t <parameter>buflen</parameter></paramdef>
87       </funcprototype>
88     </funcsynopsis>
89   </refsynopsisdiv>
90
91
92   <refsect1><title>Description</title>
93   <para>
94   <indexterm><primary>cipher functions</primary>
95              <secondary>gcry_cipher_ctl</secondary>
96              </indexterm>
97   <function>gcry_cipher_ctl</function> controls various aspects of the
98   cipher module and specific cipher contexts.  A couple of macros may
99   be used for convenience:
100
101   gcry_cipher_setkey(h,k,l)
102   gcry_cipher_setiv(h,k,l)
103   gcry_cipher_sync(h)
104
105   </para>
106 </refentry>
107
108
109 <!--**********************************************
110 ***********  cipher info   ***********************
111 ***********************************************-->
112 <refentry>
113   <refnamediv>
114     <refname>gcry_cipher_info</refname>
115     <refpurpose>return information about a cipher context</refpurpose>
116   </refnamediv>
117
118   <refsynopsisdiv>
119     <funcsynopsis>
120       <funcsynopsisinfo>
121       #include &lt;gcrypt.h&gt;
122       </funcsynopsisinfo>
123       <funcprototype>
124         <funcdef>int <function>gcry_cipher_info</function></funcdef>
125         <paramdef>GCRY_CIPHER_HD <parameter>h</parameter></paramdef>
126         <paramdef>int <parameter>what</parameter></paramdef>
127       </funcprototype>
128     </funcsynopsis>
129   </refsynopsisdiv>
130
131
132   <refsect1><title>Description</title>
133   <para>
134   <indexterm><primary>cipher functions</primary>
135              <secondary>gcry_cipher_info</secondary>
136              </indexterm>
137   <function>gcry_cipher_info</function> is used to retrieve various
138   information about a cipher context or the cipher module in general.
139   Currently no information is available.
140   </para>
141 </refentry>
142
143
144 <!--**********************************************
145 ***********  cipher algo name   ******************
146 ***********************************************-->
147 <refentry>
148   <refnamediv>
149     <refname>gcry_cipher_algo_name</refname>
150     <refpurpose>return the name of a cipher algorithm</refpurpose>
151   </refnamediv>
152
153   <refsynopsisdiv>
154     <funcsynopsis>
155       <funcsynopsisinfo>
156       #include &lt;gcrypt.h&gt;
157       </funcsynopsisinfo>
158       <funcprototype>
159         <funcdef>const char *<function>gcry_cipher_algo_name</function></funcdef>
160         <paramdef>int <parameter>algo</parameter></paramdef>
161       </funcprototype>
162     </funcsynopsis>
163   </refsynopsisdiv>
164
165
166   <refsect1><title>Description</title>
167   <para>
168   <indexterm><primary>cipher functions</primary>
169              <secondary>gcry_cipher_algo_name</secondary>
170              </indexterm>
171   <function>gcry_cipher_algo_name</function> returns a string with the
172   name of the cipher algorithm <parameter>algo</parameter>.  If the algorithm
173   is not known or an other error occured, an empty string is return.  This
174   function will never return NULL.
175   </para>
176 </refentry>
177
178 <!--**********************************************
179 ***********  cipher map name  ********************
180 ***********************************************-->
181 <refentry>
182   <refnamediv>
183     <refname>gcry_cipher_map_name</refname>
184     <refpurpose>return an algorithm identifier for string</refpurpose>
185   </refnamediv>
186
187   <refsynopsisdiv>
188     <funcsynopsis>
189       <funcsynopsisinfo>
190       #include &lt;gcrypt.h&gt;
191       </funcsynopsisinfo>
192       <funcprototype>
193         <funcdef>int <function>gcry_cipher_map_name</function></funcdef>
194         <paramdef>const char *<parameter>name</parameter></paramdef>
195       </funcprototype>
196     </funcsynopsis>
197   </refsynopsisdiv>
198
199
200   <refsect1><title>Description</title>
201   <para>
202   <indexterm><primary>cipher functions</primary>
203              <secondary>gcry_cipher_map_name</secondary>
204              </indexterm>
205   <function>gcry_cipher_map_name</function> returns the algorithm identifier
206   for the cipher algorithm described by the string <parameter>name</parameter>.
207   If this algorith is not available 0 is returned.
208   </para>
209 </refentry>
210
211 <!--**********************************************
212 ***********  cipher en/decryptlose  **************
213 ***********************************************-->
214 <refentry>
215   <refnamediv>
216     <refname>gcry_cipher_encrypt</refname>
217     <refname>gcry_cipher_decrypt</refname>
218     <refpurpose>encrypt data or decrypt data</refpurpose>
219   </refnamediv>
220
221   <refsynopsisdiv>
222     <funcsynopsis>
223       <funcsynopsisinfo>
224       #include &lt;gcrypt.h&gt;
225       </funcsynopsisinfo>
226       <funcprototype>
227         <funcdef>int <function>gcry_cipher_encrypt</function></funcdef>
228         <paramdef>GCRY_CIPHER_HD <parameter>h</parameter></paramdef>
229         <paramdef>unsigned char <parameter>out</parameter></paramdef>
230         <paramdef>size_t <parameter>outsize</parameter></paramdef>
231         <paramdef>unsigned char <parameter>in</parameter></paramdef>
232         <paramdef>size_t <parameter>insize</parameter></paramdef>
233       </funcprototype>
234       <funcprototype>
235         <funcdef>int <function>gcry_cipher_decrypt</function></funcdef>
236         <paramdef>GCRY_CIPHER_HD <parameter>h</parameter></paramdef>
237         <paramdef>unsigned char <parameter>out</parameter></paramdef>
238         <paramdef>size_t <parameter>outsize</parameter></paramdef>
239         <paramdef>unsigned char <parameter>in</parameter></paramdef>
240         <paramdef>size_t <parameter>insize</parameter></paramdef>
241       </funcprototype>
242     </funcsynopsis>
243   </refsynopsisdiv>
244
245
246   <refsect1><title>Description</title>
247   <para>
248   <indexterm><primary>cipher functions</primary>
249              <secondary>gcry_cipher_encrypt</secondary>
250              </indexterm>
251   <indexterm><primary>cipher functions</primary>
252              <secondary>gcry_cipher_decrypt</secondary>
253              </indexterm>
254   <function>gcry_cipher_encrypt</function> is used to encrypt the data.
255   the complemetary function <function>gcry_cipher_decrypt</function> is
256   be used to decrypt the data. The calling convention for both functions
257   is the same.
258   </para>
259   <para>These functions can either work in place or with two buffers.
260   Overlapping buffers are not allowed.
261   </para>
262 </refentry>
263