Debian Codegraph @

docs/manual.htm

raw ◀ ▶
1 Debian patch touch this file
1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2 <html>
3 <head>
4 <title>libGringotts manual</title>
5 <meta http-equiv="content-type" content="text/html; charset=ISO-8859-15">
6 </head>
7 <body BGCOLOR="#EAE8E3">
8 <h1 align="center">libGringotts manual</h1>
9 <p>As we said, libGringotts provides a simple way to process your data, or save them to some file, in an higly configurable and completely secure way, using strong encryption and hashing algorithms to ensure no one will ever be able to read them (well... as long as they don't know the password... ;-). It includes some other useful features, like generation of encrypted temporary files, secure memory management, and functions for the evaluation of password quality.</p>
10 <p>Here is a complete documentation on libGringotts' interface and internals. First, you'll be presented with the various non-standard <a href="#tdefs">data structures</a> and <a href="#ecodes">codes</a> you'll use; after these, the <a href="#fx">functions</a> will be introduced. Maybe you'll want to step right to the <a href="#ie">examples</a>, which are a sort of tutorial; finally, the very <a href="#formats">file format</a> will be described.</p>
11 <h3>Table of contents</h3>
12 <ul>
13 <li><a href="#tdefs">Typedefs &amp; enumerations</a></li>
14 <ul>
15 <li><a href="#enums">Enumerations</a></li>
16 <li><a href="#encaps">Encapsulations ("objects")</a></li>
17 </ul>
18 <li><a href="#ecodes">Error codes</a></li>
19 <li><a href="#fx">Functions</a></li>
20 <ul>
21 <li><a href="#gpf">General purpose functions</a></li>
22 <li><a href="#lcrf">libGringotts context-related functions</a></li>
23 <li><a href="#lkrf">libGringotts keyholder-related functions</a></li>
24 <li><a href="#mtmedf">Memory-to-memory encryption/decryption functions</a></li>
25 <li><a href="#fedf">File encryption/decryption functions</a></li>
26 <li><a href="#etfrf">Encrypted Temporary File-related functions</a></li>
27 <li><a href="#muf">Miscellaneous utility functions</a></li>
28 </ul>
29 <li><a href="#ie">An example is better than 10<sup>3</sup> words</a></li>
30 <li><a href="#formats">In depth: the file formats</a></li>
31 <ul>
32 <li><a href="#v3">libGringotts file format, version 3</a></li>
33 <li><a href="#v2">libGringotts file format, version 2</a></li>
34 <li><a href="#v1">libGringotts file format, version 1</a></li>
35 </ul>
36 </ul>
37
38 <a name="tdefs"><h3>Typedefs &amp; enumerations</h3></a>
39 <p>In the various functions, you'll use the following types. Some are enumerations,
40 that can take fixed values (also described below), some other just encapsulations,
41 that keep a bunch of data about the context, or other info.</p>
42 <a name="enums"><h4>Enumerations</h4></a>
43 <p>The default values are shown in <b>bold text</b>.</p>
44 <table cellpadding="2" cellspacing="2" border="0">
45 <tbody>
46 <tr>
47 <th valign="top" align="left"><a name="grg_crypt_algo"></a>grg_crypt_algo</th>
48 <td valign="middle" rowspan="1" colspan="2"><i><small>this parameter describes the algorithm used for encryption.</small></i></td>
49 </tr>
50 <tr>
51 <td valign="top"></td>
52 <td valign="top">GRG_RIJNDAEL_128</td>
53 <td valign="middle" rowspan="2" colspan="1">The AES winner, <b>Rijndael</b>.</td>
54 </tr>
55 <tr>
56 <td valign="top"></td>
57 <td valign="top">GRG_AES</td>
58 </tr>
59 <tr>
60 <td valign="top"></td>
61 <td valign="top"><b>GRG_SERPENT</b></td>
62 <td valign="top">The AES finalist <b>Serpent</b></td>
63 </tr>
64 <tr>
65 <td valign="top"></td>
66 <td valign="top">GRG_TWOFISH</td>
67 <td valign="top">The AES finalist <b>Twofish</b></td>
68 </tr>
69 <tr>
70 <td valign="top"></td>
71 <td valign="top">GRG_CAST_256</td>
72 <td valign="top">The AES contestant<b> CAST 256</b></td>
73 </tr>
74 <tr>
75 <td valign="top"></td>
76 <td valign="top">GRG_SAFERPLUS</td>
77 <td valign="top">The AES contestant <b>Safer+</b></td>
78 </tr>
79 <tr>
80 <td valign="top"></td>
81 <td valign="top">GRG_LOKI97</td>
82 <td valign="top">The AES contestant <b>Loki 97</b></td>
83 </tr>
84 <tr>
85 <td valign="top"></td>
86 <td valign="top">GRG_3DES</td>
87 <td valign="top"><b>Triple DES</b> algorithm</td>
88 </tr>
89 <tr>
90 <td valign="top"></td>
91 <td valign="top">GRG_RIJNDAEL_256</td>
92 <td valign="top"><b>Rijndael</b>, with 256-bit block size</td>
93 </tr>
94 <tr>
95 <th valign="top" align="left"><a name="grg_hash_algo">grg_hash_algo</a></th>
96 <td valign="middle" rowspan="1" colspan="2"><i><small>the algorithm used to hash the password to obtain the encryption key</small></i></td>
97 </tr>
98 <tr>
99 <td valign="top"></td>
100 <td valign="top">GRG_SHA1</td>
101 <td valign="top"><b>SHA-1</b> 160-bit hash algorithm</td>
102 </tr>
103 <tr>
104 <td valign="top"></td>
105 <td valign="top"><b>GRG_RIPEMD_160</b></td>
106 <td valign="top"><b>RIPEMD-160</b> 160-bit hash algorithm</td>
107 </tr>
108 <tr>
109 <th valign="top" align="left"><a name="grg_comp_algo"></a>grg_comp_algo</th>
110 <td valign="middle" rowspan="1" colspan="2"><small><i>the algorithm used to compress data before saving it</i></small></td>
111 </tr>
112 <tr>
113 <td valign="top"></td>
114 <td valign="top"><b>GRG_ZLIB</b></td>
115 <td valign="top"><b>ZLib</b> deflate algorithm</td>
116 </tr>
117 <tr>
118 <td valign="top"></td>
119 <td valign="top">GRG_BZIP</td>
120 <td valign="top"><b>BZip2</b> algorithm (more efficient, slower)</td>
121 </tr>
122 <tr>
123 <th valign="top" align="left"><a name="grg_comp_ratio"></a>grg_comp_ratio</th>
124 <td valign="middle" rowspan="1" colspan="2"><small><i>the compression ratio</i></small></td>
125 </tr>
126 <tr>
127 <td valign="top"></td>
128 <td valign="top">GRG_LVL_NONE</td>
129 <td valign="top">No compression stage at all</td>
130 </tr>
131 <tr>
132 <td valign="top"></td>
133 <td valign="top">GRG_LVL_FAST</td>
134 <td valign="top">Compression, level 3</td>
135 </tr>
136 <tr>
137 <td valign="top"></td>
138 <td valign="top">GRG_LVL_GOOD</td>
139 <td valign="top">Compression, level 6</td>
140 </tr>
141 <tr>
142 <td valign="top"></td>
143 <td valign="top"><b>GRG_LVL_BEST</b></td>
144 <td valign="top">Compression, level 9</td>
145 </tr>
146 <tr>
147 <th valign="top" align="left"><a name="grg_security_lvl"></a>grg_security_lvl</th>
148 <td valign="middle" rowspan="1" colspan="2"><small><i>fine-tuning of some details regarding security</i></small></td>
149 </tr>
150 <tr>
151 <td valign="top"></td>
152 <td valign="top"><b>GRG_SEC_NORMAL</b></td>
153 <td valign="top">Normal behavior, enough for all purposes.</td>
154 </tr>
155 <tr>
156 <td valign="top"></td>
157 <td valign="top">GRG_SEC_PARANOIA</td>
158 <td valign="top">Paranoid settings. For now, it uses <tt>/dev/random</tt> instead of <tt>/dev/urandom</tt>, slowing things a good deal.</td>
159 </tr>
160 </tbody>
161 </table>
162 <a name="encaps"><h4>Encapsulations ("objects")</h4></a>
163 <table cellpadding="2" cellspacing="2" border="0">
164 <tbody>
165 <tr>
166 <th valign="top" align="left"><a name="GRG_CTX">GRG_CTX</a></th>
167 <td valign="top">An object that represent the "context" of the usage
168 of the libraries. It should be created at the beginning of the application,
169 as it contains all the parameters that regulate the behaviour of the encryption
170 process. Anyway, most of these parameters can be changed at runtime, i.e.
171 to specify different algorithms according to the user's choices.</td>
172 </tr>
173 <tr>
174 <th valign="top" align="left"><a name="GRG_KEY"></a>GRG_KEY</th>
175 <td valign="top">An object that encapsulates the encryption key (a
176 "keyholder"). It's created starting from a password, and must be re-created
177 anytime the password changes. The password itself isn't stored in memory
178 in plaintext, this way, as it's immediately hashed.</td>
179 </tr>
180 <tr>
181 <th valign="top" align="left"><a name="GRG_TMPFILE"></a>GRG_TMPFILE</th>
182 <td valign="top">This objects represents an encrypted temporary file, and must be used to indentify a particular instance of it in the various operations. Encrypted temporary files haven't a name in the filesystem, but the reference is only held by the program; they are encrypted with a random key, so lurkers can't retrieve data from raw readings of the filesystem. Anyway, they aren't compressed, for sake of speed. An enc. temp file can be created, and written once; then you have read-only access on the data.</td>
183 </tr>
184 </tbody>
185 </table>
186 <h3><a name="ecodes">Error codes</a></h3>
187 <p>When the value returned by a encryption/decryption function is negative,
188 it represents an error. The following values may be used to compare the code
189 with, and find its cause.</p>
190 <table cellpadding="2" cellspacing="2" border="0">
191 <tbody>
192 <tr align="left">
193 <th valign="top" align="left">GRG_OK</th>
194 <td valign="top">All went fine! :-)</td>
195 </tr>
196 <tr align="left">
197 <th valign="top" align="left">GRG_WRITE_COMP_ERR</th>
198 <td valign="top">Can't compress data. Probably a fault or misinstallation
199 of the compression libraries used.</td>
200 </tr>
201 <tr align="left">
202 <th valign="top" align="left">GRG_WRITE_ENC_INIT_ERR</th>
203 <td valign="top">Can't initialize libMCrypt for compression. Probably
204 a wrong installation</td>
205 </tr>
206 <tr align="left">
207 <th valign="top" align="left">GRG_WRITE_FILE_ERR</th>
208 <td valign="top">Can't open the file for writing. Check permissions...</td>
209 </tr>
210 <tr align="left">
211 <th valign="top" align="left">GRG_TMP_NOT_WRITEABLE</th>
212 <td valign="top">A temporary file has been written once, and can't be written anymore. You can only read it, or close it and create another one.</td>
213 </tr>
214 <tr align="left">
215 <th valign="top" align="left">GRG_READ_FILE_ERR</th>
216 <td valign="top">Can't open the file for reading. Check permissions,
217 or file existence.</td>
218 </tr>
219 <tr align="left">
220 <th valign="top" align="left">GRG_READ_MAGIC_ERR</th>
221 <td valign="top">The file doesn't start with the magic number ("header") provided. Probably wrong file type.</td>
222 </tr>
223 <tr align="left">
224 <th valign="top" align="left">GRG_READ_CRC_ERR</th>
225 <td valign="top">The CRC check failed. File corrupted...</td>
226 </tr>
227 <tr align="left">
228 <th valign="top" align="left">GRG_READ_PWD_ERR</th>
229 <td valign="top">The supplied password was wrong</td>
230 </tr>
231 <tr align="left">
232 <th valign="top" align="left">GRG_READ_ENC_INIT_ERR</th>
233 <td valign="top">Can't initialize libMCrypt for decompression. Probably a wrong installation.</td>
234 </tr>
235 <tr align="left">
236 <th valign="top" align="left">GRG_READ_UNSUPPORTED_VERSION</th>
237 <td valign="top">The file format version of the file you're attempting to read is not supported.</td>
238 </tr>
239 <tr>
240 <th valign="top" align="left">GRG_READ_COMP_ERR</th>
241 <td valign="top">Can't decompress data. Probably a fault or misinstallation of the compression libraries used.</td>
242 </tr>
243 <tr>
244 <th valign="top" align="left">GRG_TMP_NOT_YET_WRITTEN</th>
245 <td valign="top">A temporary file can't be read, because it hasn't been written yet.</td>
246 </tr>
247 </tbody>
248 </table>
249 <p>The following can be returned by the fuction <code>grg_file_shred()</code>:</p>
250 <table cellpadding="2" cellspacing="2" border="0">
251 <tbody>
252 <tr align="left">
253 <th valign="top" align="left">GRG_SHRED_CANT_OPEN_FILE</th>
254 <td valign="top">The function doesn't manage to open the file to wipe.</td>
255 </tr>
256 <tr align="left">
257 <th valign="top" align="left">GRG_SHRED_YET_LINKED</th>
258 <td valign="top">The file you're trying to wipe have more than one hard link. Overwriting it with random data would destroy also the other file.</td>
259 </tr>
260 <tr align="left">
261 <th valign="top" align="left">GRG_SHRED_CANT_MMAP</th>
262 <td valign="top">The system can't memory map the file. It's probably a system problem; see <code>man 2 mmap</code> for hints.</td>
263 </tr>
264 </tbody>
265 </table>
266 <p>The following are generic errors, that can be returned by all functions that return an <b>int</b>:</p>
267 <table cellpadding="2" cellspacing="2" border="0">
268 <tbody>
269 <tr align="left">
270 <th valign="top" align="left">GRG_MEM_ALLOCATION_ERR</th>
271 <td valign="top">The system can't allocate memory. Probably memory is full, or there are serious system errors.</td>
272 </tr>
273 <tr align="left">
274 <th valign="top" align="left">GRG_ARGUMENT_ERR</th>
275 <td valign="top">An argument supplied to the function isn't valid; probably, you're supplying a NULL pointer when not allowed.</td>
276 </tr>
277 </tbody>
278 </table>
279
280 <a name="fx"><h3>Functions</h3></a>
281 <p>So, here we are. At the very core :-)</p>
282 <a name="gpf"><h4>General purpose functions</h4></a>
283 <p>
284 <code>unsigned char *<b>grg_get_version</b> (void);</code><br>
285 <blockquote>
286 This returns the version of the library, as a string. For example, "1.0.0" or "5.2.22". It's allocated, so you must <code>free()</code> it after use.
287 </blockquote>
288 </p>
289 <p>
290 <code>unsigned int <b>grg_get_int_version</b> (void);</code><br>
291 <blockquote>
292 The version, again, but as a number; this way, you can make comparisons between versions. For example, "1.0.0"=10000 and "5.2.22"=50222, so it's TRUE that 50222 &gt; 10000.
293 </blockquote>
294 </p>
295 <a name="lcrf"><h4>libGringotts context (<a href="#GRG_CTX">GRG_CTX</a>) related functions</h4></a>
296 <p>
297 <code><a href="#GRG_CTX">GRG_CTX</a> <b>grg_context_initialize</b> (const unsigned char *<b>header</b>, const <a href="#grg_crypt_algo">grg_crypt_algo</a> <b>crypt_algo</b>, const <a href="#grg_hash_algo">grg_hash_algo</a> <b>hash_algo</b>, const <a href="#grg_comp_algo">grg_comp_algo</a> <b>comp_algo</b>, const <a href="#grg_comp_ratio">grg_comp_ratio</a> <b>comp_lvl</b>, const <a href="#grg_security_lvl">grg_security_lvl</a> <b>sec_lvl</b>);</code><br>
298 <blockquote>
299 Initializes a new libGringotts session, given its parameters. The <b>header</b> is a 3-letter string that specifies which will be the first three bytes of your files, to use as identifier. The other parameters are the algorithms and settings you want to use, as described in the "Enumerations" section, above. If the function returns <b>NULL</b>, an error occoured.</blockquote>
300 </p>
301 <p>
302 <code><a href="#GRG_CTX">GRG_CTX</a> <b>grg_context_initialize_defaults</b> (const unsigned char *<b>header</b>);</code><br>
303 <blockquote>
304 Initializes a new libGringotts session, with some default values. The <b>header</b> is the same as the previous function, and like that one, if the return value is <b>NULL</b>, it indicates an error.</blockquote>
305 </p>
306 <p>
307 <code>void <b>grg_context_free</b> (<a href="#GRG_CTX">GRG_CTX</a> <b>gctx</b>);</code><br>
308 <blockquote>Frees the resources encapsulated in a <a href="#GRG_CTX">context</a> <b>gctx</b>. It MUST be always called, upon a session termination.
309 </blockquote>
310 </p>
311 <p>
312 <code><a href="#grg_crypt_algo">grg_crypt_algo</a> <b>grg_ctx_get_crypt_algo</b> (const <a href="#GRG_CTX">GRG_CTX</a> <b>gctx</b>);<br>
313 <a href="#grg_hash_algo">grg_hash_algo</a> <b>grg_ctx_get_hash_algo</b> (const <a href="#GRG_CTX">GRG_CTX</a> <b>gctx</b>);<br>
314 <a href="#grg_comp_algo">grg_comp_algo</a> <b>grg_ctx_get_comp_algo</b> (const <a href="#GRG_CTX">GRG_CTX</a> <b>gctx</b>);<br>
315 <a href="#grg_comp_ratio">grg_comp_ratio</a> <b>grg_ctx_get_comp_ratio</b> (const <a href="#GRG_CTX">GRG_CTX</a> <b>gctx</b>);<br>
316 <a href="#grg_security_lvl">grg_security_lvl</a> <b>grg_ctx_get_security_lvl</b> (const <a href="#GRG_CTX">GRG_CTX</a> <b>gctx</b>);</code><br>
317 <blockquote>
318 Gets the various settings encapsulated in a <a href="#GRG_CTX">context</a>.
319 </blockquote>
320 </p>
321 <p>
322 <code>void <b>grg_ctx_set_crypt_algo</b> (<a href="#GRG_CTX">GRG_CTX</a> <b>gctx</b>, const <a href="#grg_crypt_algo">grg_crypt_algo</a> <b>crypt_algo</b>);<br>
323 void <b>grg_ctx_set_hash_algo</b> (<a href="#GRG_CTX">GRG_CTX</a> <b>gctx</b>, const <a href="#grg_hash_algo">grg_hash_algo</a> <b>hash_algo</b>);<br>
324 void <b>grg_ctx_set_comp_algo</b> (<a href="#GRG_CTX">GRG_CTX</a> <b>gctx</b>, const <a href="#grg_comp_algo">grg_comp_algo</a> <b>comp_algo</b>);<br>
325 void <b>grg_ctx_set_comp_ratio</b> (<a href="#GRG_CTX">GRG_CTX</a> <b>gctx</b>, const <a href="#grg_comp_ratio">grg_comp_ratio</a> <b>comp_ratio</b>);<br>
326 void <b>grg_ctx_set_security_lvl</b> (<a href="#GRG_CTX">GRG_CTX</a> <b>gctx</b>, const <a href="#grg_security_lvl">grg_security_lvl</a> <b>sec_level</b>);</code><br>
327 <blockquote>
328 These functions changes the settings for a given context, to adapt its future behaviour to the programmer's needings.
329 </blockquote>
330 </p>
331 <p>
332 <code>unsigned int <b>grg_get_key_size_static</b> (const <a href="#grg_crypt_algo">grg_crypt_algo</a> <b>crypt_algo</b>);<br>
333 unsigned int <b>grg_get_key_size</b> (const <a href="#GRG_CTX">GRG_CTX</a> <b>gctx</b>);<br>
334 unsigned int <b>grg_get_block_size_static</b> (const <a href="#grg_crypt_algo">grg_crypt_algo</a> <b>crypt_algo</b>);<br>
335 unsigned int <b>grg_get_block_size</b> (const <a href="#GRG_CTX">GRG_CTX</a> <b>gctx</b>);</code><br>
336 <blockquote>
337 Intuitively enough, they obtain informations on the size of block and key of an ancryption algorithm; they can be obtained by the algorithm id (the <b>_static</b> version of each) or by the one encapsulated in a specific <a href="#GRG_CTX">context</a>.
338 </blockquote>
339 </p>
340 <a name="lkrf"><h4>libGringotts keyholder (<a href="#GRG_KEY">GRG_KEY</a>) related functions</h4></a>
341 <p>
342 <code><a href="#GRG_KEY">GRG_KEY</a> <b>grg_key_gen</b> (const unsigned char *<b>pwd</b>, const int <b>pwd_len</b>);</code><br>
343 <blockquote>
344 Generates a new <a href="#GRG_KEY">keyholder</a>, from a password <b>pwd</b> (that can be any byte sequence), of length <b>pwd_len</b>. If <b>pwd_len</b> is <b>-1</b>, the length is autodetected, and the password must be NULL-terminated. It returns <b>NULL</b> on errors.<br>
345 <i>Note: the password is not stored in plaintext, and the memory occupied by the keyholder is fixed and does not depend on the password size.</i>
346 </blockquote>
347 </p>
348 <p>
349 <code><a href="#GRG_KEY">GRG_KEY</a> <b>grg_key_clone</b> (const <a href="#GRG_KEY">GRG_KEY</a> <b>src</b>);</code><br>
350 <blockquote>
351 Clones a <a href="#GRG_KEY">keyholder</a> <b>src</b> into a new one.
352 </blockquote>
353 </p>
354 <p>
355 <code>int <b>grg_key_compare</b> (const <a href="#GRG_KEY">GRG_KEY</a> <b>k1</b>, const <a href="#GRG_KEY">GRG_KEY</a> <b>k2</b>);</code><br>
356 <blockquote>
357 Compares two <a href="#GRG_KEY">keyholders</a>, <b>k1</b> and <b>k2</b>. If they are equals, it returns <b>0</b>; else, <b>1</b>.
358 </blockquote>
359 </p>
360 <p>
361 <code>void <b>grg_key_free</b> (const <a href="#GRG_CTX">GRG_CTX</a> <b>gctx</b>, <a href="#GRG_KEY">GRG_KEY</a> <b>key</b>);</code><br>
362 <blockquote>Releases the resources associated with the <a href="#GRG_KEY">keyholder</a> <b>key</b>, using the <a href="#GRG_CTX">context</a> <b>gctx</b>. It securely wipes it, so no one can recover its data later on.
363 </blockquote>
364 </p>
365 <a name="mtmedf"><h4>Memory-to-memory encryption/decryption functions</h4></a>
366 <p>
367 <code><a href="#ecodes">int</a> <b>grg_validate_mem</b> (const <a href="#GRG_CTX">GRG_CTX</a> <b>gctx</b>, const void *<b>mem</b>, const long <b>memDim</b>);</code><br>
368 <blockquote>
369 Validates a memory segment containing libGringotts' data. In other words, it simply says if it's valid or not, and if not, why. Returns one of the <a href="#ecodes">error codes</a> described above. The memory address is located at <b>mem</b>, of length <b>memDim</b>.
370 </blockquote>
371 </p>
372 <p>
373 <code><a href="#ecodes">int</a> <b>grg_update_gctx_from_mem</b> (<a href="#GRG_CTX">GRG_CTX</a> <b>gctx</b>, const void *<b>mem</b>, const long <b>memDim</b>);</code><br>
374 <blockquote>
375 Detects the algorithms used to produce a libGringotts-encoded memory segment (at <b>mem</b>, of length <b>memDim</b>), and updates the <a href="#GRG_CTX">context</a> <b>gctx</b> to contain these data.
376 </blockquote>
377 </p>
378 <p>
379 <code><a href="#ecodes">int</a> <b>grg_encrypt_mem</b> (const <a href="#GRG_CTX">GRG_CTX</a> <b>gctx</b>, const <a href="#GRG_KEY">GRG_KEY</a> <b>keystruct</b>, void **<b>mem</b>, long *<b>memDim</b>, const long <b>origDim</b>);</code><br>
380 <blockquote>
381 Encodes data to a memory region. The encryption is performed with the password contained in <b>keystruct</b> and the settings specified in <b>gctx</b>. The encoded data produced will be written to a newly-allocated (to free after use) memory region, pointed by *<b>mem</b>, and its length will be written to *<b>memDim</b>. <b>origData</b> and <b>origDim</b> are, respectively, the data to be encoded (which can be any byte sequence, not just strings) and their length. As ever, if <b>origDim</b> = -1 the length is autodetected, and <b>origData</b> must be NULL-terminated. The return value is a libGringotts <a href="#ecodes">error code</a>, to compare in the table above.
382 </blockquote>
383 </p>
384 <p>
385 <code><a href="#ecodes">int</a> <b>grg_decrypt_mem</b> (const <a href="#GRG_CTX">GRG_CTX</a> <b>gctx</b>, const <a href="#GRG_KEY">GRG_KEY</a> <b>keystruct</b>, const void *<b>mem</b>, const long <b>memDim</b>, unsigned char **<b>origData</b>, long *<b>origDim</b>);</code><br>
386 <blockquote>
387 Reads data from a libGringotts-encoded data sequence, located at <b>mem</b> (of size <b>memDim</b>), using the password in <b>keystruct</b>. The <a href="#GRG_CTX">context</a> <b>gctx</b> is adopted, and updated with the algorithms used to encrypt the file. It returns an <a href="#ecodes">error code</a> in case of errors. The read data are stored in <b>origData</b>, and their length in <b>origLen</b>, that can be NULL if you don't want to retrieve length. The former is allocated dinamically, so you'll want to <code>free()</code> (better, <code><a href="#grg_free">grg_free()</a></code> ;-) it after use.
388 </blockquote>
389 </p>
390 <a name="fedf"><h4>File encryption/decryption functions (finally ;-)</h4></a>
391 <p>
392 These are basically the same functions as above, but they read and save data from files instead than memory. If you work with files, please use these, because they are more integrated than operating with memory and then interface it on files, resulting in faster &amp; safer I/O.
393 </p>
394 <p>
395 <code><a href="#ecodes">int</a> <b>grg_validate_file</b> (const <a href="#GRG_CTX">GRG_CTX</a> <b>gctx</b>, const unsigned char *<b>path</b>);</code><br>
396 <blockquote>
397 Validates a libGringotts' file (at <b>path</b>). In other words, it simply says if it's valid or not, and if not, why. Returns one of the <a href="#ecodes">error codes</a> described above.
398 </blockquote>
399 </p>
400 <p>
401 <code><a href="#ecodes">int</a> <b>grg_update_gctx_from_file</b> (<a href="#GRG_CTX">GRG_CTX</a> <b>gctx</b>, const unsigned char *<b>path</b>);</code><br>
402 <blockquote>
403 Detects the algorithms used to produce a file (at <b>path</b>), and updates the <a href="#GRG_CTX">context</a> <b>gctx</b> to contain these data.
404 </blockquote>
405 </p>
406 <p>
407 <code><a href="#ecodes">int</a> <b>grg_encrypt_file</b> (const <a href="#GRG_CTX">GRG_CTX</a> <b>gctx</b>, const <a href="#GRG_KEY">GRG_KEY</a> <b>keystruct</b>, const unsigned char *<b>path</b>, const unsigned char *<b>origData</b>, const long <b>origDim</b>);</code><br>
408 <blockquote>
409 Writes data to a new libGringotts file. The encryption is performed with the password contained in <b>keystruct</b> and the settings specified in <b>gctx</b>; the file produced will be written to <b>path</b>. <b>origData</b> and <b>origDim</b> are, respectively, the data to be encoded (which can be any byte sequence, not just strings) and their length. As ever, if <b>origDim</b> = -1 the length is autodetected, and <b>origData</b> must be NULL-terminated. The return value is a libGringotts <a href="#ecodes">error code</a>, to compare in the table above.
410 </blockquote>
411 </p>
412 <p>
413 <code><a href="#ecodes">int</a> <b>grg_decrypt_file</b> (const <a href="#GRG_CTX">GRG_CTX</a> <b>gctx</b>, const <a href="#GRG_KEY">GRG_KEY</a> <b>keystruct</b>, const unsigned char *<b>path</b>, unsigned char **<b>origData</b>, long *<b>origDim</b>);</code><br>
414 <blockquote>
415 Reads data from an encrypted file located at <b>path</b>, using the password in <b>keystruct</b>. The <a href="#GRG_CTX">context</a> <b>gctx</b> is adopted, and updated with the algorithms used to encrypt the file. It returns an <a href="#ecodes">error code</a> in case of errors. The read data are stored in <b>origData</b>, and their length in <b>origLen</b>, that can be NULL if you don't want to retrieve length. The former is allocated dinamically, so you'll want to <code>free()</code> (better, <code><a href="#grg_free">grg_free()</a></code> ;-) it after use.
416 </blockquote>
417 </p>
418 <p>There is also a "direct" version of each of these functions, that accepts an already opened file descriptor instead of a filename. This may be desirable to avoid race conditions, i.e. when validating a file before actually opening it. <b>Notice</b> that these don't close the file descriptor; that operation is up to you.</b></p>
419 <p><code>
420 <a href="#ecodes">int</a> <b>grg_validate_file_direct</b> (const <a href="#GRG_CTX">GRG_CTX</a> <b>gctx</b>, const int <b>fd</b>);<br>
421 <a href="#ecodes">int</a> <b>grg_update_gctx_from_file_direct</b> (<a href="#GRG_CTX">GRG_CTX</a> <b>gctx</b>, const int <b>fd</b>);<br>
422 <a href="#ecodes">int</a> <b>grg_encrypt_file_direct</b> (const <a href="#GRG_CTX">GRG_CTX</a> <b>gctx</b>, const <a href="#GRG_KEY">GRG_KEY</a> <b>keystruct</b>, const int <b>fd</b>, const unsigned char *<b>origData</b>, const long <b>origDim</b>);<br>
423 <a href="#ecodes">int</a> <b>grg_decrypt_file_direct</b> (const <a href="#GRG_CTX">GRG_CTX</a> <b>gctx</b>, const <a href="#GRG_KEY">GRG_KEY</a> <b>keystruct</b>, const int <b>fd</b>, unsigned char **<b>origData</b>, long *<b>origDim</b>);
424 </code></p>
425 <a name="etfrf"><h4>Encrypted Temporary File-related functions</h4></a>
426 <p>
427 <code><a href="#GRG_TMPFILE">GRG_TMPFILE</a> <b>grg_tmpfile_gen</b> (const <a href="#GRG_CTX">GRG_CTX</a> <b>gctx</b>);</code><br>
428 <blockquote>
429 Creates a new encrypted tempfile, and returns an handler to it. The file will be written with the encryption algorithm contained in the context <em>at this time</em>; any modification to it will not be reflected on the file. The file is encrypted with a random key, unavailable to the user. The handler will be used to write (once) data to the file, and retrieve them later.
430 </blockquote>
431 </p>
432 <p>
433 <code><a href="#ecodes">int</a> <b>grg_tmpfile_write</b> (const <a href="#GRG_CTX">GRG_CTX</a> <b>gctx</b>, <a href="#GRG_TMPFILE">GRG_TMPFILE</a> tf, const unsigned char *<b>data</b>, long <b>data_len</b>);</code><br>
434 <blockquote>
435 This function is used to write <b>data</b> (of length <b>data_len</b>, <b>-1</b> as ever if <b>data</b> is NULL-terminated) in the temporary file represented by <b>tf</b>. This can be done only once. The file, after this, becomes read-only. Returns an <a href="#ecodes">error code</a> as usual.
436 </blockquote>
437 </p>
438 <p>
439 <code><a href="#ecodes">int</a> <b>grg_tmpfile_read</b> (const <a href="#GRG_CTX">GRG_CTX</a> <b>gctx</b>, <a href="#GRG_TMPFILE">GRG_TMPFILE</a> tf, unsigned char **<b>data</b>, long *<b>data_len</b>);</code><br>
440 <blockquote>
441 This function is used to read <b>data</b> from a temporary file. The length is stored in <b>data_len</b>, but you can specify NULL if you don't want to retrieve it. This operation can be done only after a successful writing. Returns an <a href="#ecodes">error code</a> as usual.
442 </blockquote>
443 </p>
444 <p>
445 <code>void <b>grg_tmpfile_close</b> (const <a href="#GRG_CTX">GRG_CTX</a> <b>gctx</b>, <a href="#GRG_TMPFILE">GRG_TMPFILE</a> tf);</code><br>
446 <blockquote>
447 Releases all the resources incapsulated in the tmpfile handler, in a secure way.
448 </blockquote>
449 </p>
450 <a name="muf"><h4>Miscellaneous utility functions</h4></a>
451 <p>
452 <code>unsigned char *<b>grg_rnd_seq</b> (const <a href="#GRG_CTX">GRG_CTX</a> <b>gctx</b>, const unsigned int <b>size</b>);</code><br>
453 <code>void <b>grg_rnd_seq_direct</b> (const <a href="#GRG_CTX">GRG_CTX</a> <b>gctx</b>, unsigned char *<b>toOverwrite</b>, const unsigned int <b>size</b>);</code><br>
454 <blockquote>
455 Returns a random byte sequence, basing on the <a href="#GRG_CTX">context</a> <b>gctx</b>, of size <b>size</b>. The <code>_direct</code> version overwrites a (valid) string provided by the user (it's his responsibility to check that string and <b>size</b> are coherent; if <b>size</b> = -1 it will be autodetected), the other allocates a new string, to <code>free()</code> afterwards.
456 </blockquote>
457 </p>
458 <p>
459 <code>unsigned char <b>grg_rnd_chr</b> (const <a href="#GRG_CTX">GRG_CTX</a> <b>gctx</b>);</code><br>
460 <blockquote>
461 Returns a random byte.
462 </blockquote>
463 </p>
464 <p>
465 <code>void <a name="grg_free"></a><b>grg_free</b> (const <a href="#GRG_CTX">GRG_CTX</a> <b>gctx</b>, void *<b>alloc_data</b>, const long <b>dim</b>);</code><br>
466 <blockquote>
467 Frees allocated memory (pointed by <b>alloc_data</b>), overwriting it with random trash. Precious when you have sensitive data in memory, and you do want to ensure that they aren't readable in any way, afterwards. <b>dim</b> is the dimension of the data to wipe, or <b>-1</b> if it's NULL-terminated.
468 </blockquote>
469 </p>
470 <p>
471 <code>double <b>grg_ascii_pwd_quality</b> (const unsigned char *<b>pwd</b>, const long <b>pwd_len</b>);</code><br>
472 <blockquote>
473 Gives an estimation of the quality of a string password, on a scale from 0 to 1. <b>pwd_len</b> is the length of the password <b>pwd</b>; you can specify <b>-1</b> if it's NULL-terminated.
474 </blockquote>
475 </p>
476 <p>
477 <code>double <b>grg_file_pwd_quality</b> (const unsigned char *<b>pwd_path</b>);</code><br>
478 <blockquote>
479 Gives an estimation of the quality of a file (on the disk, at <b>pwd_path</b>), when using it as a password, on a scale from 0 to 1.
480 </blockquote>
481 </p>
482
483 <p><code>
484 unsigned char* <b>grg_encode64</b> (const unsigned char *<b>in</b>, const unsigned int <b>inlen</b>, unsigned int *<b>outlen</b>);<br>
485 unsigned char* <b>grg_decode64</b> (const unsigned char *<b>in</b>, const unsigned int <b>inlen</b>, unsigned int *<b>outlen</b>);<br>
486 </code>
487 <blockquote>
488 These function convert a generic sequence of bytes to/from the base64 format. Useful for email sending, xml storing, etc.
489 </blockquote>
490 </p>
491 <p>
492 <code>int <b>grg_file_shred</b> (const char *<b>path</b>, const int <b>npasses</b>);</code><br>
493 <blockquote>
494 Securely wipes a file, overwriting it <b>npasses</b> times with random data. The data can't be recovered, once done this; be careful. This option still have some limitations, as it takes the assumption that the filesystem overwrites files <i>in place</i>: for some FSs this isn't true. See <code>man 1 shred</code> for details.
495 </blockquote>
496 </p>
497 <a name="ie"><h3>An example is better than a 10<sup>3</sup> words</h3></a>
498 <p>
499 Confused? Don't be! It's simple! :-) Here is a couple of examples of how to tie it all together. This is a piece of code that writes data to a file:
500 <pre>
501 #include &lt;libgringotts.h&gt;
502 #include &lt;string.h&gt;
503
504 <i>[...]</i>
505
506 {
507 <i>//initialization of structures</i>
508 GRG_CTX context = grg_context_initialize_defaults ("TRY");
509 GRG_KEY keyholder = grg_key_gen ("This is a nice password", -1);
510
511 <i>//let's produce some data to encode</i>
512 unsigned char *plaintext = "These are some valuable and important data!";
513 unsigned int txtlen = strlen (plaintext);
514 unsigned char *filepath = "/home/mano/somefile.try"; <i>//extension is not relevant</i>
515
516 <i>//now we change some settings, and leave the others as defaults</i>
517 grg_ctx_set_crypt_algo (context, GRG_TWOFISH);
518 grg_ctx_set_comp_algo (context, GRG_BZIP);
519
520 <i>//finally, let's save!</i>
521 grg_encrypt_file (context, keyholder, filepath, plaintext, txtlen); <i>//txtlen could be -1</i>
522
523 <i>//always remember to clean up leftovers...</i>
524 grg_key_free (context, keyholder);
525 grg_context_free (context);
526 }
527
528 <i>[...]</i>
529
530 </pre>
531 <p>
532 To decode, things are even simpler:
533 </p>
534 <pre>
535 #include &lt;libgringotts.h&gt;
536 #include &lt;stdio.h&gt;
537
538 <i>[...]</i>
539
540 {
541 <i>//again, initialization of structures
542 //or you can reuse the same as before</i>
543 GRG_CTX context = grg_context_initialize_defaults ("TRY");
544 GRG_KEY keyholder = grg_key_gen ("This is a nice password", -1);
545
546 unsigned int *filepath = "/home/mano/somefile.try";
547
548 <i>//here the library will put the decoded data</i>
549 unsigned char *plaintext;
•550 long int txtlen;
551
552 <i>//we are ready to perform the decryption</i>
553 grg_decrypt_file (context, keyholder, filepath, &amp;plaintext, &amp;txtlen);
554
555 <i>//now, data are stored in the two variables and in the
556 //context, that's changed accordingly. Let's use them...</i>
557 printf ("Decrypted data are %d long, and are \"%s\"\n", txtlen, plaintext);
558 if (grg_ctx_get_crypt_algo (context) == GRG_TWOFISH)
559 printf ("You encrypted the file with Twofish\n");
560 else
561 printf ("You didn't encrypt the file with Twofish\n");
562
563 <i>//as always, remember to clean up leftovers...</i>
564 grg_key_free (context, keyholder);
565 grg_free (context, plaintext, txtlen);
566 grg_context_free (context);
567 }
568
569 <i>[...]</i>
570
571 </pre>
572 <p>This silly thing writes some stuff to a temporary file, then reads it.</p>
573 <pre>
574
575 <i>[...]</i>
576
577 {
578 <i>//init of structs</i>
579 GRG_CTX gctx = grg_context_initialize_defaults ("tRy");
580 GRG_TMPFILE tf = grg_tmpfile_gen (gctx);
581 unsigned char *try;
•582 long int dim;
583
584 <i>//writes some stupid data</i>
585 grg_tmpfile_write (gctx, tf, "S0M3 S7UP1D DA7A", 16);
586
587 <i>[...]</i>
588
589 <i>//then reads it. Simple...</i>
•590 grg_tmpfile_read (gctx, tf, &amp;try, &dim);
591
592 <i>//Freedom... freedom... freedom... ;-)</i>
593 grg_tmpfile_close (gctx, tf);
594 grg_context_free (gctx);
595
596 <i>//Use those data!</i>
•597 printf("Data were %s, of length %ld\n", try, dim);
598 }
599
600 <i>[...]</i>
601
602 </pre>
603 <a name="formats"><h3>In depth: the file formats</h3></a>
604 <p>A description of the inners of the libGringotts File Format follows. Please use it... in any way you like! ;-)</p>
605 <a name="v3"><h4>libGringotts file format, version 3</h4></a>
606 <p>A file has this structure:</p>
607 <font size="+1">
608 <pre>
609 HEADER | VERSION | CRC32 | ALGO | IV | <i>CRC32</i> | <i>DATA_LEN</i> | <b>DATA</b>
610 </pre>
611 </font>
612 <ul>
613 <li>the part written in <i>italic</i> is encrypted;</li>
614 <li>the part written in <b>bold</b> is compressed and encrypted</li>
615 </ul>
616 <ul>
617 <li><b>HEADER</b>: an unique file format ID [it <b>must</b> be 3 bytes long]</li>
618 <li><b>VERSION</b>: the file format version ("3") [1b]</li>
619 <li><b>CRC32</b>: the CRC32 of the remaining file part [4b]<br>
620 <i>The second is used to check the correctness of the password</i></li>
621 <li><b>ALGO</b> is a bitfield defined as follow:
622 <pre>
623 IAAABCDD
624 MSB^ ^LSB
625 </pre>
626 where:
627 <ul>
628 <li><b>I</b>: ignored, set it to <b>0</b></li>
629 <li><b>A</b>: encryption algorithm</li>
630 <ul>
631 <li>000 -&gt; AES (Rjindael-128)</li>
632 <li><b>001 -&gt; Serpent</b></li>
633 <li>010 -&gt; Twofish</li>
634 <li>011 -&gt; CAST-256</li>
635 <li>100 -&gt; SAFER+</li>
636 <li>101 -&gt; LOKI97</li>
637 <li>110 -&gt; 3DES</li>
638 <li>111 -&gt; Rjindael-256</li>
639 </ul>
640 <li><b>B</b>: hashing algorithm</li>
641 <ul>
642 <li>0 -&gt; SHA-1</li>
643 <li><b>1 -&gt; RIPEMD-160</b></li>
644 </ul>
645 <li><b>C</b>: compression type</li>
646 <ul>
647 <li><b>0 -&gt; ZLib</b></li>
648 <li>1 -&gt; libBZ2</li>
649 </ul>
650 <li><b>D</b>: compression level</li>
651 <ul>
652 <li>00 -&gt; none (0)</li>
653 <li>01 -&gt; fast (3)</li>
654 <li>10 -&gt; good (6)</li>
655 <li><b>11 -&gt; best (9)</b></li>
656 </ul>
657 </ul>
658 in <b>bold</b> the defaults (0 001 1 0 11 = 0x1b).</li>
659 <li><b>IV</b> is the Initialization Vector of the encryption function. It's randomly generated at file encryption, and its dimension varies from 8 to 32 bytes accordingly to encryption algorithm block size</li>
660 <li><b>DATA_LEN</b>: the length of the <i>uncompressed</i> DATA [4b]</li>
661 <li><b>DATA</b>: the data stored in this file</li>
662 </ul>
663 <p>
664 This way, the final file length is typically (compressed DATA)+33b, and this format allows <i>compressed</i> data size up to 512 Mb ( 2<sup>4*8</sup> ). Fair enough.</p>
665 <p>
666 The data are encrypted using the given algorithm with a key derived from the password. This key is calculated hashing the password data with the chosen algorithm, for the length required by the encryption algorithm, and using the S2K algorithm <code>KEYGEN_S2K_SIMPLE</code> of MHash. The key obtained is XOR'ed with the IV, repeated as many times as needed; this way, I have a different key for each saving of the file, increasing security.</p>
667 <a name="v2"><h4>libGringotts file format, version 2</h4></a>
668 <p>This was analogous to format 3, but used KEYGEN_MCRYPT for key generation; Bob Mathews found that this had a minor weakness, so I changed it. It isn't supported anymore from libGringotts 1.0.0; use Gringotts 0.7.0 to convert an old file in this format.</p>
669 <a name="v1"><h4>libGringotts file format, version 1</h4></a>
670 <p>It didn't allow any choice of the algorithms; it used SHA-256 for hashing, and SERPENT for encryption.</p>
671 <p>It isn't supported anymore, starting from libGringotts 2 (Gringotts 0.6.0). If you still have some file encrypted with this, use an older Gringotts (between 0.4.2 and 0.5.9) to convert it to v2, and then Gringotts 0.7.0 to convert to v3.</p>
672 </body>
673 </html>