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