lib/gc.h

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