include/openssl/rand_drbg.h

   1 /*
   2  * Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
   3  *
   4  * Licensed under the OpenSSL license (the "License").  You may not use
   5  * this file except in compliance with the License.  You can obtain a copy
   6  * in the file LICENSE in the source distribution or at
   7  * https://www.openssl.org/source/license.html
   8  */
   9
  10 #ifndef HEADER_DRBG_RAND_H
  11 # define HEADER_DRBG_RAND_H
  12
  13 # include <time.h>
  14 # include <openssl/ossl_typ.h>
  15
  16
  17 /* In CTR mode, disable derivation function ctr_df */
  18 # define RAND_DRBG_FLAG_CTR_NO_DF            0x1
  19
  20 /*
  21  * Default security strength (in the sense of [NIST SP 800-90Ar1])
  22  *
  23  * NIST SP 800-90Ar1 supports the strength of the DRBG being smaller than that
  24  * of the cipher by collecting less entropy. The current DRBG implemantion does
  25  * not take RAND_DRBG_STRENGTH into account and sets the strength of the DRBG
  26  * to that of the cipher.
  27  *
  28  * RAND_DRBG_STRENGTH is currently only used for the legacy RAND
  29  * implementation.
  30  *
  31  * Currently supported ciphers are: NID_aes_128_ctr, NID_aes_192_ctr and
  32  * NID_aes_256_ctr
  33  *
  34  * TODO(DRBG): would be nice to have the NID and strength configurable
  35  */
  36 # define RAND_DRBG_STRENGTH             256
  37 # define RAND_DRBG_NID                  NID_aes_256_ctr
  38
  39
  40 # ifdef  __cplusplus
  41 extern "C" {
  42 # endif
  43
  44 /*
  45  * Object lifetime functions.
  46  */
  47 RAND_DRBG *RAND_DRBG_new(int type, unsigned int flags, RAND_DRBG *parent);
  48 RAND_DRBG *RAND_DRBG_secure_new(int type, unsigned int flags, RAND_DRBG *parent);
  49 int RAND_DRBG_set(RAND_DRBG *drbg, int type, unsigned int flags);
  50 int RAND_DRBG_instantiate(RAND_DRBG *drbg,
  51                           const unsigned char *pers, size_t perslen);
  52 int RAND_DRBG_uninstantiate(RAND_DRBG *drbg);
  53 void RAND_DRBG_free(RAND_DRBG *drbg);
  54
  55 /*
  56  * Object "use" functions.
  57  */
  58 int RAND_DRBG_reseed(RAND_DRBG *drbg,
  59                      const unsigned char *adin, size_t adinlen);
  60 int RAND_DRBG_generate(RAND_DRBG *drbg, unsigned char *out, size_t outlen,
  61                        int prediction_resistance,
  62                        const unsigned char *adin, size_t adinlen);
  63 int RAND_DRBG_bytes(RAND_DRBG *drbg, unsigned char *out, size_t outlen);
  64
  65 int RAND_DRBG_set_reseed_interval(RAND_DRBG *drbg, unsigned int interval);
  66 int RAND_DRBG_set_reseed_time_interval(RAND_DRBG *drbg, time_t interval);
  67
  68 int RAND_DRBG_set_reseed_defaults(
  69                                   unsigned int master_reseed_interval,
  70                                   unsigned int slave_reseed_interval,
  71                                   time_t master_reseed_time_interval,
  72                                   time_t slave_reseed_time_interval
  73                                   );
  74
  75 RAND_DRBG *RAND_DRBG_get0_master(void);
  76 RAND_DRBG *RAND_DRBG_get0_public(void);
  77 RAND_DRBG *RAND_DRBG_get0_private(void);
  78
  79 /*
  80  * EXDATA
  81  */
  82 # define RAND_DRBG_get_ex_new_index(l, p, newf, dupf, freef) \
  83     CRYPTO_get_ex_new_index(CRYPTO_EX_INDEX_DRBG, l, p, newf, dupf, freef)
  84 int RAND_DRBG_set_ex_data(RAND_DRBG *dctx, int idx, void *arg);
  85 void *RAND_DRBG_get_ex_data(const RAND_DRBG *dctx, int idx);
  86
  87 /*
  88  * Callback function typedefs
  89  */
  90 typedef size_t (*RAND_DRBG_get_entropy_fn)(RAND_DRBG *ctx,
  91                                            unsigned char **pout,
  92                                            int entropy, size_t min_len,
  93                                            size_t max_len);
  94 typedef void (*RAND_DRBG_cleanup_entropy_fn)(RAND_DRBG *ctx,
  95                                              unsigned char *out, size_t outlen);
  96 typedef size_t (*RAND_DRBG_get_nonce_fn)(RAND_DRBG *ctx, unsigned char **pout,
  97                                          int entropy, size_t min_len,
  98                                          size_t max_len);
  99 typedef void (*RAND_DRBG_cleanup_nonce_fn)(RAND_DRBG *ctx,
 100                                            unsigned char *out, size_t outlen);
 101
 102 int RAND_DRBG_set_callbacks(RAND_DRBG *dctx,
 103                             RAND_DRBG_get_entropy_fn get_entropy,
 104                             RAND_DRBG_cleanup_entropy_fn cleanup_entropy,
 105                             RAND_DRBG_get_nonce_fn get_nonce,
 106                             RAND_DRBG_cleanup_nonce_fn cleanup_nonce);
 107
 108
 109 # ifdef  __cplusplus
 110 }
 111 # endif
 112
 113 #endif