EXTERNAL_HEADERS/corecrypto/ccrng.h

   1 /* Copyright (c) (2010,2011,2012,2013,2014,2015,2016,2017,2018,2019) Apple Inc. All rights reserved.
   2  *
   3  * corecrypto is licensed under Apple Inc.’s Internal Use License Agreement (which
   4  * is contained in the License.txt file distributed with corecrypto) and only to
   5  * people who accept that license. IMPORTANT:  Any license rights granted to you by
   6  * Apple Inc. (if any) are limited to internal use within your organization only on
   7  * devices and computers you own or control, for the sole purpose of verifying the
   8  * security characteristics and correct functioning of the Apple Software.  You may
   9  * not, directly or indirectly, redistribute the Apple Software or any portions thereof.
  10  */
  11
  12 #ifndef _CORECRYPTO_CCRNG_H_
  13 #define _CORECRYPTO_CCRNG_H_
  14
  15 #include <corecrypto/cc.h>
  16
  17 #define CCRNG_STATE_COMMON \
  18     int (*CC_SPTR(ccrng_state, generate))(struct ccrng_state *rng, size_t outlen, void *out);
  19
  20 /*!
  21  @type      struct ccrng_state
  22  @abstract  Default state structure. Do not instantiate. ccrng() returns a reference to this structure
  23  */
  24 struct ccrng_state {
  25     CCRNG_STATE_COMMON
  26 };
  27
  28 /*!
  29  @function   ccrng
  30  @abstract   Initializes an AES-CTR mode cryptographic random number generator and returns the statically-allocated rng object.
  31              Getting a pointer to a ccrng has never been simpler!
  32              Call this function, get an rng object and then pass the object to ccrng_generate() to generate randoms.
  33              ccrng() may be called more than once. It returns pointer to the same object on all calls.
  34
  35  @result  a cryptographically secure random number generator or NULL if fails
  36
  37  @discussion
  38  - It is significantly faster than using the system /dev/random
  39  - FIPS Compliant: NIST SP800-90A + FIPS 140-2
  40  - Seeded from the system entropy.
  41  - Provides at least 128bit security if the system provide 2bit of entropy / byte.
  42  - Entropy accumulation
  43  - Backtracing resistance
  44  - Prediction break with frequent (asynchronous) reseed
  45  */
  46
  47 struct ccrng_state *ccrng(int *error);
  48
  49 /*!
  50  @function   ccrng_generate
  51  @abstract   Generate `outlen` bytes of output, stored in `out`, using ccrng_state `rng`.
  52
  53  @param rng  `struct ccrng_state` representing the state of the RNG.
  54  @param outlen  Amount of random bytes to generate.
  55  @param out  Pointer to memory where random bytes are stored, of size at least `outlen`.
  56
  57  @result 0 on success and nonzero on failure.
  58  */
  59 #define ccrng_generate(rng, outlen, out) \
  60     ((rng)->generate((struct ccrng_state *)(rng), (outlen), (out)))
  61
  62 /*!
  63   @function ccrng_uniform
  64   @abstract Generate a random value in @p [0, bound).
  65
  66   @param rng   The state of the RNG.
  67   @param bound The exclusive upper bound on the output.
  68   @param rand  A pointer to a single @p uint64_t to store the result.
  69
  70   @result Returns zero iff the operation is successful.
  71  */
  72 int ccrng_uniform(struct ccrng_state *rng, uint64_t bound, uint64_t *rand);
  73
  74 #endif /* _CORECRYPTO_CCRNG_H_ */