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 CCERR_DEVICE                   -100
  17 #define CCERR_INTERUPTS                -101
  18 #define CCERR_CRYPTO_CONFIG            -102
  19 #define CCERR_PERMS                    -103
  20 #define CCERR_PARAMETER                -104
  21 #define CCERR_MEMORY                   -105
  22 #define CCERR_FILEDESC                 -106
  23 #define CCERR_OUT_OF_ENTROPY           -107
  24 #define CCERR_INTERNAL                 -108
  25 #define CCERR_ATFORK                   -109
  26 #define CCERR_OVERFLOW                 -110
  27
  28 #define CCRNG_STATE_COMMON                                                          \
  29     int (*generate)(struct ccrng_state *rng, size_t outlen, void *out);
  30
  31 /* default state structure. Do not instantiate, ccrng() returns a reference to this structure */
  32 struct ccrng_state {
  33     CCRNG_STATE_COMMON
  34 };
  35
  36 /*!
  37  @function   ccrng
  38  @abstract   initializes a AES-CTR mode cryptographic random number generator and returns the statically alocated rng object.
  39              Getting a pointer to a ccrng has never been simpler!
  40              Call this function, get an rng object and then pass the object to ccrng_generate() to generate randoms.
  41              ccrng() may be called more than once. It returns pointer to the same object on all calls.
  42
  43  @result  a cryptographically secure random number generator or NULL if fails
  44
  45  @discussion
  46  - It is significantly faster than using the system /dev/random
  47  - FIPS Compliant: NIST SP800-80A + FIPS 140-2
  48  - Seeded from the system entropy.
  49  - Provides at least 128bit security if the system provide 2bit of entropy / byte.
  50  - Entropy accumulation
  51  - Backtracing resistance
  52  - Prediction break with frequent (asynchronous) reseed
  53  */
  54
  55 struct ccrng_state *ccrng(int *error);
  56
  57 //call this macro with the rng argument set to output of the call to the ccrng() function
  58 #define ccrng_generate(rng, outlen, out) ((rng)->generate((rng), (outlen), (out)))
  59
  60 #endif /* _CORECRYPTO_CCRNG_H_ */