1 /* gc.h --- Header file for implementation agnostic crypto wrapper API.
2 * Copyright (C) 2002, 2003, 2004, 2005 Simon Josefsson
4 * This file is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU General Public License as published
6 * by the Free Software Foundation; either version 2, or (at your
7 * option) any later version.
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 * General Public License for more details.
14 * You should have received a copy of the GNU General Public License
15 * along with this file; if not, write to the Free Software
16 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
35 GC_PKCS5_INVALID_ITERATION_COUNT,
36 GC_PKCS5_INVALID_DERIVED_KEY_LENGTH,
37 GC_PKCS5_DERIVED_KEY_TOO_LONG
39 typedef enum Gc_rc Gc_rc;
49 typedef enum Gc_hash Gc_hash;
55 typedef enum Gc_hash_mode Gc_hash_mode;
57 typedef void *gc_hash_handle;
59 #define GC_MD5_DIGEST_SIZE 16
60 #define GC_SHA1_DIGEST_SIZE 20
74 typedef enum Gc_cipher Gc_cipher;
81 typedef enum Gc_cipher_mode Gc_cipher_mode;
83 typedef void *gc_cipher_handle;
85 /* Call before respectively after any other functions. */
86 extern Gc_rc gc_init (void);
87 extern void gc_done (void);
89 /* Memory allocation (avoid). */
90 typedef void *(*gc_malloc_t) (size_t n);
91 typedef int (*gc_secure_check_t) (const void *);
92 typedef void *(*gc_realloc_t) (void *p, size_t n);
93 typedef void (*gc_free_t) (void *);
94 extern void gc_set_allocators (gc_malloc_t func_malloc,
95 gc_malloc_t secure_malloc,
96 gc_secure_check_t secure_check,
97 gc_realloc_t func_realloc,
101 extern Gc_rc gc_cipher_open (Gc_cipher cipher, Gc_cipher_mode mode,
102 gc_cipher_handle * outhandle);
103 extern Gc_rc gc_cipher_setkey (gc_cipher_handle handle,
104 size_t keylen, const char *key);
105 extern Gc_rc gc_cipher_setiv (gc_cipher_handle handle,
106 size_t ivlen, const char *iv);
107 extern Gc_rc gc_cipher_encrypt_inline (gc_cipher_handle handle,
108 size_t len, char *data);
109 extern Gc_rc gc_cipher_decrypt_inline (gc_cipher_handle handle,
110 size_t len, char *data);
111 extern Gc_rc gc_cipher_close (gc_cipher_handle handle);
115 extern Gc_rc gc_hash_open (Gc_hash hash, Gc_hash_mode mode,
116 gc_hash_handle * outhandle);
117 extern Gc_rc gc_hash_clone (gc_hash_handle handle, gc_hash_handle * outhandle);
118 extern size_t gc_hash_digest_length (Gc_hash hash);
119 extern void gc_hash_hmac_setkey (gc_hash_handle handle,
120 size_t len, const char *key);
121 extern void gc_hash_write (gc_hash_handle handle,
122 size_t len, const char *data);
123 extern const char *gc_hash_read (gc_hash_handle handle);
124 extern void gc_hash_close (gc_hash_handle handle);
126 /* Compute a hash value over buffer IN of INLEN bytes size using the
127 algorithm HASH, placing the result in the pre-allocated buffer OUT.
128 The required size of OUT depends on HASH, and is generally
129 GC_<HASH>_DIGEST_SIZE. For example, for GC_MD5 the output buffer
130 must be 16 bytes. The return value is 0 (GC_OK) on success, or
131 another Gc_rc error code. */
133 gc_hash_buffer (Gc_hash hash, const void *in, size_t inlen, char *out);
135 /* One-call interface. */
136 extern Gc_rc gc_md5 (const void *in, size_t inlen, void *resbuf);
137 extern Gc_rc gc_sha1 (const void *in, size_t inlen, void *resbuf);
138 extern Gc_rc gc_hmac_md5 (const void *key, size_t keylen,
139 const void *in, size_t inlen,
141 extern Gc_rc gc_hmac_sha1 (const void *key, size_t keylen,
142 const void *in, size_t inlen,
145 /* Derive cryptographic keys from a password P of length PLEN, with
146 salt S of length SLEN, placing the result in pre-allocated buffer
147 DK of length DKLEN. An iteration count is specified in C, where a
148 larger value means this function take more time (typical iteration
149 counts are 1000-20000). This function "stretches" the key to be
150 exactly dkLen bytes long. GC_OK is returned on success, otherwise
151 an Gc_rc error code is returned. */
153 gc_pbkdf2_sha1 (const char *P, size_t Plen,
154 const char *S, size_t Slen,
156 char *DK, size_t dkLen);
161 From: Simon Josefsson <jas@extundo.com>
162 Subject: Re: generic crypto
163 Newsgroups: gmane.comp.lib.gnulib.bugs
164 Cc: bug-gnulib@gnu.org
165 Date: Fri, 07 Oct 2005 12:50:57 +0200
166 Mail-Copies-To: nobody
168 Paul Eggert <eggert@CS.UCLA.EDU> writes:
170 > Simon Josefsson <jas@extundo.com> writes:
172 >> * Perhaps the /dev/?random reading should be separated into a separate
173 >> module? It might be useful outside of the gc layer too.
175 > Absolutely. I've been meaning to do that for months (for a "shuffle"
176 > program I want to add to coreutils), but hadn't gotten around to it.
177 > It would have to be generalized a bit. I'd like to have the file
178 > descriptor cached, for example.
180 I'll write a separate module for that part.
182 I think we should even add a good PRNG that is re-seeded from
183 /dev/?random frequently. GnuTLS can need a lot of random data on a
184 big server, more than /dev/random can supply. And /dev/urandom might
185 not be strong enough. Further, the security of /dev/?random can also
188 >> I'm also not sure about the names of those functions, they suggest
189 >> a more higher-level API than what is really offered (i.e., the
190 >> names "nonce" and "pseudo_random" and "random" imply certain
191 >> cryptographic properties).
193 > Could you expand a bit more on that? What is the relationship between
194 > nonce/pseudorandom/random and the /dev/ values you are using?
196 There is none, that is the problem.
198 Applications generally need different kind of "random" numbers.
199 Sometimes they just need some random data and doesn't care whether it
200 is possible for an attacker to compute the string (aka a "nonce").
201 Sometimes they need data that is very difficult to compute (i.e.,
202 computing it require inverting SHA1 or similar). Sometimes they need
203 data that is not possible to compute, i.e., it wants real entropy
204 collected over time on the system. Collecting the last kind of random
205 data is very expensive, so it must not be used too often. The second
206 kind of random data ("pseudo random") is typically generated by
207 seeding a good PRNG with a couple of hundred bytes of real entropy
208 from the "real random" data pool. The "nonce" is usually computed
209 using the PRNG as well, because PRNGs are usually fast.
211 Pseudo-random data is typically used for session keys. Strong random
212 data is often used to generate long-term keys (e.g., private RSA
215 Of course, there are many subtleties. There are several different
216 kind of nonce:s. Sometimes a nonce is just an ever-increasing
217 integer, starting from 0. Sometimes it is assumed to be unlikely to
218 be the same as previous nonces, but without a requirement that the
219 nonce is possible to guess. MD5(system clock) would thus suffice, if
220 it isn't called too often. You can guess what the next value will be,
221 but it will always be different.
223 The problem is that /dev/?random doesn't offer any kind of semantic
224 guarantees. But applications need an API that make that promise.
226 I think we should do this in several steps:
228 1) Write a module that can read from /dev/?random.
230 2) Add a module for a known-good PRNG suitable for random number
231 generation, that can be continuously re-seeded.
233 3) Add a high-level module that provide various different randomness
234 functions. One for nonces, perhaps even different kind of nonces,
235 one for pseudo random data, and one for strong random data. It is
236 not clear whether we can hope to achieve the last one in a portable
239 Further, it would be useful to allow users to provide their own
240 entropy source as a file, used to seed the PRNG or initialize the
241 strong randomness pool. This is used on embedded platforms that
242 doesn't have enough interrupts to hope to generate good random data.
244 > For example, why not use OpenBSD's /dev/arandom?
246 I don't trust ARC4. For example, recent cryptographic efforts
247 indicate that you must throw away the first 512 bytes generated from
248 the PRNG for it to be secure. I don't know whether OpenBSD do this.
249 Further, I recall some eprint paper on RC4 security that didn't
252 While I trust the random devices in OpenBSD more than
253 Solaris/AIX/HPUX/etc, I think that since we need something better on
254 Solaris/AIX/HPUX we'd might as well use it on OpenBSD or even Linux
257 > Here is one thought. The user could specify a desired quality level
258 > range, and the implementation then would supply random data that is at
259 > least as good as the lower bound of the range. I.e., ihe
260 > implementation refuses to produce any random data if it can't generate
261 > data that is at least as good as the lower end of the range. The
262 > upper bound of the range is advice from the user not to be any more
263 > expensive than that, but the implementation can ignore the advice if
264 > it doesn't have anything cheaper.
266 I'm not sure this is a good idea. Users can't really be expected to
267 understand this. Further, applications need many different kind of
268 random data. Selecting the randomness level for each by the user will
271 I think it is better if the application decide, from its cryptographic
272 requirement, what entropy quality it require, and call the proper API.
273 Meeting the implied semantic properties should be the job for gnulib.
275 >> Perhaps gc_dev_random and gc_dev_urandom?
277 > To some extent. I'd rather insulate the user from the details of
278 > where the random numbers come from. On the other hand we need to
279 > provide a way for applications to specify a file that contains
280 > random bits, so that people can override the defaults.
284 This may require some thinking before it is finalized. Is it ok to
285 install the GC module as-is meanwhile? Then I can continue to add the
286 stuff that GnuTLS need, and then come back to re-working the
287 randomness module. That way, we have two different projects that use
288 the code. GnuTLS includes the same randomness code that was in GNU
289 SASL and that is in the current gc module. I feel much more
290 comfortable working in small steps at a time, rather then working on
291 this for a long time in gnulib and only later integrate the stuff in