EXTERNAL_HEADERS/corecrypto/ccrng.h

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