EXTERNAL_HEADERS/corecrypto/ccdrbg.h

   1 /*
   2  *  ccdrbg.h
   3  *  corecrypto
   4  *
   5  *  Created on 08/17/2010
   6  *
   7  *  Copyright (c) 2010,2011,2012,2014,2015 Apple Inc. All rights reserved.
   8  *
   9  */
  10
  11 /*!
  12  @header corecrypto/ccdrbg.h
  13  @abstract The functions provided in ccdrbg.h implement high-level accessors
  14  to cryptographically secure random numbers.
  15
  16  */
  17
  18 #ifndef _CORECRYPTO_CCDRBG_H_
  19 #define _CORECRYPTO_CCDRBG_H_
  20
  21 #include <corecrypto/cc.h>
  22 #include <corecrypto/ccdrbg_impl.h>
  23
  24 /* error codes */
  25 #define CCDRBG_STATUS_OK 0
  26 #define CCDRBG_STATUS_ERROR (-1)
  27 #define CCDRBG_STATUS_NEED_RESEED (-2)
  28 #define CCDRBG_STATUS_PARAM_ERROR (-3)
  29 // If this value is returned, the caller must abort or panic the process for security reasons.
  30 // for example in the case of catastrophic error in
  31 // http://csrc.nist.gov/publications/drafts/800-90/sp800_90a_r1_draft.pdf
  32 // ccdrbg calls abort() or panic(), if they are available in the system.
  33 #define CCDRBG_STATUS_ABORT (-4)
  34 /*
  35  * The maximum length of the entropy_input,  additional_input (max_additional_input_length) , personalization string
  36  * (max_personalization_string_length) and max_number_of_bits_per_request  are implementation dependent
  37  * but shall fit in a 32 bit register and be be less than or equal to the specified maximum length for the
  38  * selected DRBG mechanism (NIST 800-90A Section 10).
  39  */
  40
  41 #define CCDRBG_MAX_ENTROPY_SIZE         ((uint32_t)1<<16)
  42 #define CCDRBG_MAX_ADDITIONALINPUT_SIZE ((uint32_t)1<<16)
  43 #define CCDRBG_MAX_PSINPUT_SIZE         ((uint32_t)1<<16)
  44 #define CCDRBG_MAX_REQUEST_SIZE         ((uint32_t)1<<16) //this is the the absolute maximum in NIST 800-90A
  45 #define CCDRBG_RESEED_INTERVAL          ((uint64_t)1<<30) // must be able to fit the NIST maximum of 2^48
  46
  47
  48 /*
  49  * The entropyLength is forced to be greater or equal than the security strength.
  50  * Nonce is not forced. It either needs to have 0.5*security strength entropy. Or, a vale that is repeated
  51  * less than a 0.5*security strength bit random string.
  52  * see below or NIST  800-90A for the definition of security strength
  53  */
  54
  55 CC_INLINE int ccdrbg_init(const struct ccdrbg_info *info,
  56                         struct ccdrbg_state *drbg,
  57             size_t entropyLength, const void* entropy,
  58             size_t nonceLength, const void* nonce,
  59             size_t psLength, const void* ps)
  60 {
  61         return info->init(info, drbg, entropyLength, entropy, nonceLength, nonce, psLength, ps);
  62 }
  63
  64 /*
  65  *  The entropyLength is forced to be greater or equal than the security strength.
  66  */
  67 CC_INLINE int ccdrbg_reseed(const struct ccdrbg_info *info,
  68        struct ccdrbg_state *drbg,
  69        size_t entropyLength, const void *entropy,
  70        size_t additionalLength, const void *additional)
  71 {
  72     return info->reseed(drbg, entropyLength, entropy, additionalLength, additional);
  73 }
  74
  75
  76 CC_INLINE int ccdrbg_generate(const struct ccdrbg_info *info,
  77          struct ccdrbg_state *drbg,
  78          size_t dataOutLength, void *dataOut,
  79          size_t additionalLength, const void *additional)
  80 {
  81     return info->generate(drbg, dataOutLength, dataOut, additionalLength, additional);
  82 }
  83
  84 CC_INLINE void ccdrbg_done(const struct ccdrbg_info *info,
  85                 struct ccdrbg_state *drbg)
  86 {
  87         info->done(drbg);
  88 }
  89
  90 CC_INLINE size_t ccdrbg_context_size(const struct ccdrbg_info *drbg)
  91 {
  92     return drbg->size;
  93 }
  94
  95
  96 /*
  97  * NIST SP 800-90 CTR_DRBG
  98  * the mximum security strengh of drbg equals to the block size of the corresponding ECB.
  99  */
 100 struct ccdrbg_nistctr_custom {
 101     const struct ccmode_ecb *ecb;
 102     size_t keylen;
 103     int strictFIPS;
 104     int use_df;
 105 };
 106
 107 void ccdrbg_factory_nistctr(struct ccdrbg_info *info, const struct ccdrbg_nistctr_custom *custom);
 108
 109 /*
 110  * NIST SP 800-90 HMAC_DRBG
 111  * the maximum security strengh of drbg is half of output size of the input hash function and it internally is limited to 256 bits
 112  */
 113 extern struct ccdrbg_info ccdrbg_nistdigest_info;
 114
 115 struct ccdrbg_nisthmac_custom {
 116     const struct ccdigest_info *di;
 117     int strictFIPS;
 118 };
 119
 120 void ccdrbg_factory_nisthmac(struct ccdrbg_info *info, const struct ccdrbg_nisthmac_custom *custom);
 121
 122
 123 /*
 124  * Dummy DRBG
 125  */
 126 extern struct ccdrbg_info ccdrbg_dummy_info;
 127
 128 #endif /* _CORECRYPTO_CCDRBG_H_ */