1/* gc.h --- Header file for implementation agnostic crypto wrapper API.
2 * Copyright (C) 2002-2005, 2007-2008, 2011-2012 Free Software Foundation, Inc.
3 *
4 * This file is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU Lesser General Public License as published
6 * by the Free Software Foundation; either version 2.1, or (at your
7 * option) any later version.
8 *
9 * This file is distributed in the hope that it will be useful, but
10 * WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public License
15 * along with this file; if not, see <http://www.gnu.org/licenses/>.
16 *
17 */
18
19#ifndef GC_H
20# define GC_H
21
22/* Get size_t. */
23# include <stddef.h>
24
25enum Gc_rc
26{
27 GC_OK = 0,
28 GC_MALLOC_ERROR,
29 GC_INIT_ERROR,
30 GC_RANDOM_ERROR,
31 GC_INVALID_CIPHER,
32 GC_INVALID_HASH,
33 GC_PKCS5_INVALID_ITERATION_COUNT,
34 GC_PKCS5_INVALID_DERIVED_KEY_LENGTH,
35 GC_PKCS5_DERIVED_KEY_TOO_LONG
36};
37typedef enum Gc_rc Gc_rc;
38
39/* Hash types. */
40enum Gc_hash
41{
42 GC_MD4,
43 GC_MD5,
44 GC_SHA1,
45 GC_MD2,
46 GC_RMD160,
47 GC_SHA256,
48 GC_SHA384,
49 GC_SHA512,
50 GC_SHA224
51};
52typedef enum Gc_hash Gc_hash;
53
54enum Gc_hash_mode
55{
56 GC_HMAC = 1
57};
58typedef enum Gc_hash_mode Gc_hash_mode;
59
60typedef void *gc_hash_handle;
61
62#define GC_MD2_DIGEST_SIZE 16
63#define GC_MD4_DIGEST_SIZE 16
64#define GC_MD5_DIGEST_SIZE 16
65#define GC_RMD160_DIGEST_SIZE 20
66#define GC_SHA1_DIGEST_SIZE 20
67#define GC_SHA256_DIGEST_SIZE 32
68#define GC_SHA384_DIGEST_SIZE 48
69#define GC_SHA512_DIGEST_SIZE 64
70#define GC_SHA224_DIGEST_SIZE 24
71
72/* Cipher types. */
73enum Gc_cipher
74{
75 GC_AES128,
76 GC_AES192,
77 GC_AES256,
78 GC_3DES,
79 GC_DES,
80 GC_ARCFOUR128,
81 GC_ARCFOUR40,
82 GC_ARCTWO40,
83 GC_CAMELLIA128,
84 GC_CAMELLIA256
85};
86typedef enum Gc_cipher Gc_cipher;
87
88enum Gc_cipher_mode
89{
90 GC_ECB,
91 GC_CBC,
92 GC_STREAM
93};
94typedef enum Gc_cipher_mode Gc_cipher_mode;
95
96typedef void *gc_cipher_handle;
97
98/* Call before respectively after any other functions. */
99extern Gc_rc gc_init (void);
100extern void gc_done (void);
101
102/* Memory allocation (avoid). */
103typedef void *(*gc_malloc_t) (size_t n);
104typedef int (*gc_secure_check_t) (const void *);
105typedef void *(*gc_realloc_t) (void *p, size_t n);
106typedef void (*gc_free_t) (void *);
107extern void gc_set_allocators (gc_malloc_t func_malloc,
108 gc_malloc_t secure_malloc,
109 gc_secure_check_t secure_check,
110 gc_realloc_t func_realloc,
111 gc_free_t func_free);
112
113/* Randomness. */
114extern Gc_rc gc_nonce (char *data, size_t datalen);
115extern Gc_rc gc_pseudo_random (char *data, size_t datalen);
116extern Gc_rc gc_random (char *data, size_t datalen);
117
118/* Ciphers. */
119extern Gc_rc gc_cipher_open (Gc_cipher cipher, Gc_cipher_mode mode,
120 gc_cipher_handle *outhandle);
121extern Gc_rc gc_cipher_setkey (gc_cipher_handle handle,
122 size_t keylen, const char *key);
123extern Gc_rc gc_cipher_setiv (gc_cipher_handle handle,
124 size_t ivlen, const char *iv);
125extern Gc_rc gc_cipher_encrypt_inline (gc_cipher_handle handle,
126 size_t len, char *data);
127extern Gc_rc gc_cipher_decrypt_inline (gc_cipher_handle handle,
128 size_t len, char *data);
129extern Gc_rc gc_cipher_close (gc_cipher_handle handle);
130
131/* Hashes. */
132
133extern Gc_rc gc_hash_open (Gc_hash hash, Gc_hash_mode mode,
134 gc_hash_handle *outhandle);
135extern Gc_rc gc_hash_clone (gc_hash_handle handle, gc_hash_handle *outhandle);
136extern size_t gc_hash_digest_length (Gc_hash hash);
137extern void gc_hash_hmac_setkey (gc_hash_handle handle,
138 size_t len, const char *key);
139extern void gc_hash_write (gc_hash_handle handle,
140 size_t len, const char *data);
141extern const char *gc_hash_read (gc_hash_handle handle);
142extern void gc_hash_close (gc_hash_handle handle);
143
144/* Compute a hash value over buffer IN of INLEN bytes size using the
145 algorithm HASH, placing the result in the pre-allocated buffer OUT.
146 The required size of OUT depends on HASH, and is generally
147 GC_<HASH>_DIGEST_SIZE. For example, for GC_MD5 the output buffer
148 must be 16 bytes. The return value is 0 (GC_OK) on success, or
149 another Gc_rc error code. */
150extern Gc_rc
151gc_hash_buffer (Gc_hash hash, const void *in, size_t inlen, char *out);
152
153/* One-call interface. */
154extern Gc_rc gc_md2 (const void *in, size_t inlen, void *resbuf);
155extern Gc_rc gc_md4 (const void *in, size_t inlen, void *resbuf);
156extern Gc_rc gc_md5 (const void *in, size_t inlen, void *resbuf);
157extern Gc_rc gc_sha1 (const void *in, size_t inlen, void *resbuf);
158extern Gc_rc gc_hmac_md5 (const void *key, size_t keylen,
159 const void *in, size_t inlen, char *resbuf);
160extern Gc_rc gc_hmac_sha1 (const void *key, size_t keylen,
161 const void *in, size_t inlen, char *resbuf);
162
163/* Derive cryptographic keys from a password P of length PLEN, with
164 salt S of length SLEN, placing the result in pre-allocated buffer
165 DK of length DKLEN. An iteration count is specified in C, where a
166 larger value means this function take more time (typical iteration
167 counts are 1000-20000). This function "stretches" the key to be
168 exactly dkLen bytes long. GC_OK is returned on success, otherwise
169 a Gc_rc error code is returned. */
170extern Gc_rc
171gc_pbkdf2_sha1 (const char *P, size_t Plen,
172 const char *S, size_t Slen,
173 unsigned int c, char *DK, size_t dkLen);
174
175/*
176 TODO:
177
178 From: Simon Josefsson <jas@extundo.com>
179 Subject: Re: generic crypto
180 Newsgroups: gmane.comp.lib.gnulib.bugs
181 Cc: bug-gnulib@gnu.org
182 Date: Fri, 07 Oct 2005 12:50:57 +0200
183 Mail-Copies-To: nobody
184
185 Paul Eggert <eggert@CS.UCLA.EDU> writes:
186
187 > Simon Josefsson <jas@extundo.com> writes:
188 >
189 >> * Perhaps the /dev/?random reading should be separated into a separate
190 >> module? It might be useful outside of the gc layer too.
191 >
192 > Absolutely. I've been meaning to do that for months (for a "shuffle"
193 > program I want to add to coreutils), but hadn't gotten around to it.
194 > It would have to be generalized a bit. I'd like to have the file
195 > descriptor cached, for example.
196
197 I'll write a separate module for that part.
198
199 I think we should even add a good PRNG that is re-seeded from
200 /dev/?random frequently. GnuTLS can need a lot of random data on a
201 big server, more than /dev/random can supply. And /dev/urandom might
202 not be strong enough. Further, the security of /dev/?random can also
203 be questionable.
204
205 >> I'm also not sure about the names of those functions, they suggest
206 >> a more higher-level API than what is really offered (i.e., the
207 >> names "nonce" and "pseudo_random" and "random" imply certain
208 >> cryptographic properties).
209 >
210 > Could you expand a bit more on that? What is the relationship between
211 > nonce/pseudorandom/random and the /dev/ values you are using?
212
213 There is none, that is the problem.
214
215 Applications generally need different kind of "random" numbers.
216 Sometimes they just need some random data and doesn't care whether it
217 is possible for an attacker to compute the string (aka a "nonce").
218 Sometimes they need data that is very difficult to compute (i.e.,
219 computing it require inverting SHA1 or similar). Sometimes they need
220 data that is not possible to compute, i.e., it wants real entropy
221 collected over time on the system. Collecting the last kind of random
222 data is very expensive, so it must not be used too often. The second
223 kind of random data ("pseudo random") is typically generated by
224 seeding a good PRNG with a couple of hundred bytes of real entropy
225 from the "real random" data pool. The "nonce" is usually computed
226 using the PRNG as well, because PRNGs are usually fast.
227
228 Pseudo-random data is typically used for session keys. Strong random
229 data is often used to generate long-term keys (e.g., private RSA
230 keys).
231
232 Of course, there are many subtleties. There are several different
233 kind of nonce:s. Sometimes a nonce is just an ever-increasing
234 integer, starting from 0. Sometimes it is assumed to be unlikely to
235 be the same as previous nonces, but without a requirement that the
236 nonce is possible to guess. MD5(system clock) would thus suffice, if
237 it isn't called too often. You can guess what the next value will be,
238 but it will always be different.
239
240 The problem is that /dev/?random doesn't offer any kind of semantic
241 guarantees. But applications need an API that make that promise.
242
243 I think we should do this in several steps:
244
245 1) Write a module that can read from /dev/?random.
246
247 2) Add a module for a known-good PRNG suitable for random number
248 generation, that can be continuously re-seeded.
249
250 3) Add a high-level module that provide various different randomness
251 functions. One for nonces, perhaps even different kind of nonces,
252 one for pseudo random data, and one for strong random data. It is
253 not clear whether we can hope to achieve the last one in a portable
254 way.
255
256 Further, it would be useful to allow users to provide their own
257 entropy source as a file, used to seed the PRNG or initialize the
258 strong randomness pool. This is used on embedded platforms that
259 doesn't have enough interrupts to hope to generate good random data.
260
261 > For example, why not use OpenBSD's /dev/arandom?
262
263 I don't trust ARC4. For example, recent cryptographic efforts
264 indicate that you must throw away the first 512 bytes generated from
265 the PRNG for it to be secure. I don't know whether OpenBSD do this.
266 Further, I recall some eprint paper on RC4 security that didn't
267 inspire confidence.
268
269 While I trust the random devices in OpenBSD more than
270 Solaris/AIX/HPUX/etc, I think that since we need something better on
271 Solaris/AIX/HPUX we'd might as well use it on OpenBSD or even Linux
272 too.
273
274 > Here is one thought. The user could specify a desired quality level
275 > range, and the implementation then would supply random data that is at
276 > least as good as the lower bound of the range. I.e., ihe
277 > implementation refuses to produce any random data if it can't generate
278 > data that is at least as good as the lower end of the range. The
279 > upper bound of the range is advice from the user not to be any more
280 > expensive than that, but the implementation can ignore the advice if
281 > it doesn't have anything cheaper.
282
283 I'm not sure this is a good idea. Users can't really be expected to
284 understand this. Further, applications need many different kind of
285 random data. Selecting the randomness level for each by the user will
286 be too complicated.
287
288 I think it is better if the application decide, from its cryptographic
289 requirement, what entropy quality it require, and call the proper API.
290 Meeting the implied semantic properties should be the job for gnulib.
291
292 >> Perhaps gc_dev_random and gc_dev_urandom?
293 >
294 > To some extent. I'd rather insulate the user from the details of
295 > where the random numbers come from. On the other hand we need to
296 > provide a way for applications to specify a file that contains
297 > random bits, so that people can override the defaults.
298
299 Agreed.
300
301 This may require some thinking before it is finalized. Is it ok to
302 install the GC module as-is meanwhile? Then I can continue to add the
303 stuff that GnuTLS need, and then come back to re-working the
304 randomness module. That way, we have two different projects that use
305 the code. GnuTLS includes the same randomness code that was in GNU
306 SASL and that is in the current gc module. I feel much more
307 comfortable working in small steps at a time, rather then working on
308 this for a long time in gnulib and only later integrate the stuff in
309 GnuTLS.
310
311 Thanks,
312 Simon
313 */
314
315#endif /* GC_H */
316