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 /*
  25  * The maximum length of the entropy_input,  additional_input (max_additional_input_length) , personalization string
  26  * (max_personalization_string_length) and max_number_of_bits_per_request  are implementation dependent
  27  * but shall fit in a 32 bit register and be be less than or equal to the specified maximum length for the
  28  * selected DRBG mechanism (NIST 800-90A Section 10).
  29  */
  30
  31 #define CCDRBG_MAX_ENTROPY_SIZE         ((uint32_t)1<<16)
  32 #define CCDRBG_MAX_ADDITIONALINPUT_SIZE ((uint32_t)1<<16)
  33 #define CCDRBG_MAX_PSINPUT_SIZE         ((uint32_t)1<<16)
  34 #define CCDRBG_MAX_REQUEST_SIZE         ((uint32_t)1<<16) //this is the absolute maximum in NIST 800-90A
  35 #define CCDRBG_RESEED_INTERVAL          ((uint64_t)1<<30) // must be able to fit the NIST maximum of 2^48
  36
  37
  38 /*
  39  * The entropyLength is forced to be greater or equal than the security strength.
  40  * Nonce is not forced. It either needs to have 0.5*security strength entropy. Or, a vale that is repeated
  41  * less than a 0.5*security strength bit random string.
  42  * see below or NIST  800-90A for the definition of security strength
  43  */
  44
  45 CC_INLINE int ccdrbg_init(const struct ccdrbg_info *info,
  46                         struct ccdrbg_state *drbg,
  47             size_t entropyLength, const void* entropy,
  48             size_t nonceLength, const void* nonce,
  49             size_t psLength, const void* ps)
  50 {
  51         return info->init(info, drbg, entropyLength, entropy, nonceLength, nonce, psLength, ps);
  52 }
  53
  54 /*
  55  *  The entropyLength is forced to be greater or equal than the security strength.
  56  */
  57 CC_INLINE int ccdrbg_reseed(const struct ccdrbg_info *info,
  58        struct ccdrbg_state *drbg,
  59        size_t entropyLength, const void *entropy,
  60        size_t additionalLength, const void *additional)
  61 {
  62     return info->reseed(drbg, entropyLength, entropy, additionalLength, additional);
  63 }
  64
  65
  66 CC_INLINE int ccdrbg_generate(const struct ccdrbg_info *info,
  67          struct ccdrbg_state *drbg,
  68          size_t dataOutLength, void *dataOut,
  69          size_t additionalLength, const void *additional)
  70 {
  71     return info->generate(drbg, dataOutLength, dataOut, additionalLength, additional);
  72 }
  73
  74 CC_INLINE void ccdrbg_done(const struct ccdrbg_info *info,
  75                 struct ccdrbg_state *drbg)
  76 {
  77         info->done(drbg);
  78 }
  79
  80 CC_INLINE size_t ccdrbg_context_size(const struct ccdrbg_info *info)
  81 {
  82     return info->size;
  83 }
  84
  85
  86 /*
  87  * NIST SP 800-90 CTR_DRBG
  88  * the maximum security strengh of drbg equals to the block size of the corresponding ECB.
  89  */
  90 struct ccdrbg_nistctr_custom {
  91     const struct ccmode_ctr *ctr_info;
  92     size_t keylen;
  93     int strictFIPS;
  94     int use_df;
  95 };
  96
  97 void ccdrbg_factory_nistctr(struct ccdrbg_info *info, const struct ccdrbg_nistctr_custom *custom);
  98
  99 /*
 100  * NIST SP 800-90 HMAC_DRBG
 101  * the maximum security strengh of drbg is half of output size of the input hash function and it internally is limited to 256 bits
 102  */
 103 struct ccdrbg_nisthmac_custom {
 104     const struct ccdigest_info *di;
 105     int strictFIPS;
 106 };
 107
 108 void ccdrbg_factory_nisthmac(struct ccdrbg_info *info, const struct ccdrbg_nisthmac_custom *custom);
 109
 110 #endif /* _CORECRYPTO_CCDRBG_H_ */