lib/gc.h

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