EXTERNAL_HEADERS/corecrypto/ccdrbg.h

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