lib/gc.h

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