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