doc/man3/RAND_DRBG_new.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 RAND_DRBG_new_ex,
   6 RAND_DRBG_new,
   7 RAND_DRBG_set,
   8 RAND_DRBG_set_defaults,
   9 RAND_DRBG_instantiate,
  10 RAND_DRBG_uninstantiate,
  11 RAND_DRBG_free,
  12 RAND_DRBG_verify_zeroization
  13 - initialize and cleanup a RAND_DRBG instance
  14
  15 =head1 SYNOPSIS
  16
  17  #include <openssl/rand_drbg.h>
  18
  19  RAND_DRBG *RAND_DRBG_new_ex(OPENSSL_CTX *ctx,
  20                              int type,
  21                              unsigned int flags,
  22                              RAND_DRBG *parent);
  23
  24  RAND_DRBG *RAND_DRBG_new(int type,
  25                           unsigned int flags,
  26                           RAND_DRBG *parent);
  27
  28  int RAND_DRBG_set_defaults(int type, unsigned int flags);
  29
  30  int RAND_DRBG_instantiate(RAND_DRBG *drbg,
  31                            const unsigned char *pers, size_t perslen);
  32
  33  int RAND_DRBG_uninstantiate(RAND_DRBG *drbg);
  34
  35  void RAND_DRBG_free(RAND_DRBG *drbg);
  36  int RAND_DRBG_verify_zeroization(RAND_DRBG *drbg);
  37
  38 Deprecated since OpenSSL 3.0, can be hidden entirely by defining
  39 B<OPENSSL_API_COMPAT> with a suitable version value, see
  40 L<openssl_user_macros(7)>:
  41
  42  int RAND_DRBG_set(RAND_DRBG *drbg,
  43                    int type, unsigned int flags);
  44
  45 =head1 DESCRIPTION
  46
  47 RAND_DRBG_new_ex() creates a new DRBG instance of the given B<type> for the
  48 given OPENSSL_CTX <ctx>.
  49 The <ctx> parameter can be NULL in which case the default OPENSSL_CTX is used.
  50 RAND_DRBG_new() is the same as RAND_DRBG_new_ex() except that the default
  51 OPENSSL_CTX is always used.
  52
  53 RAND_DRBG_set() initializes the B<drbg> with the given B<type> and B<flags>.
  54 This function is deprecated.  Applications should instead use
  55 RAND_DRBG_new_ex() to create a new DRBG.
  56
  57 RAND_DRBG_set_defaults() sets the default B<type> and B<flags> for new DRBG
  58 instances.
  59
  60 The DRBG types are AES-CTR, HMAC and HASH so B<type> can be one of the
  61 following values:
  62
  63 NID_aes_128_ctr, NID_aes_192_ctr, NID_aes_256_ctr, NID_sha1, NID_sha224,
  64 NID_sha256, NID_sha384, NID_sha512, NID_sha512_224, NID_sha512_256,
  65 NID_sha3_224, NID_sha3_256, NID_sha3_384 or NID_sha3_512.
  66
  67 If this method is not called then the default type is given by NID_aes_256_ctr
  68 and the default flags are zero.
  69
  70 Before the DRBG can be used to generate random bits, it is necessary to set
  71 its type and to instantiate it.
  72
  73 The optional B<flags> argument specifies a set of bit flags which can be
  74 joined using the | operator. The supported flags are:
  75
  76 =over 4
  77
  78 =item RAND_DRBG_FLAG_CTR_NO_DF
  79
  80 Disables the use of the derivation function ctr_df. For an explanation,
  81 see [NIST SP 800-90A Rev. 1].
  82
  83 =item RAND_DRBG_FLAG_HMAC
  84
  85 Enables use of HMAC instead of the HASH DRBG.
  86
  87 =item RAND_DRBG_FLAG_MASTER
  88
  89 =item RAND_DRBG_FLAG_PUBLIC
  90
  91 =item RAND_DRBG_FLAG_PRIVATE
  92
  93 These 3 flags can be used to set the individual DRBG types created. Multiple
  94 calls are required to set the types to different values. If none of these 3
  95 flags are used, then the same type and flags are used for all 3 DRBGs in the
  96 B<drbg> chain (<master>, <public> and <private>).
  97
  98 =back
  99
 100 If a B<parent> instance is specified then this will be used instead of
 101 the default entropy source for reseeding the B<drbg>. It is said that the
 102 B<drbg> is I<chained> to its B<parent>.
 103 For more information, see the NOTES section.
 104
 105 RAND_DRBG_instantiate()
 106 seeds the B<drbg> instance using random input from trusted entropy sources.
 107 Optionally, a personalization string B<pers> of length B<perslen> can be
 108 specified.
 109 To omit the personalization string, set B<pers>=NULL and B<perslen>=0;
 110
 111 RAND_DRBG_uninstantiate()
 112 clears the internal state of the B<drbg> and puts it back in the
 113 uninstantiated state.
 114
 115 RAND_DRBG_verify_zeroization() confirms if the internal DRBG state is
 116 currently zeroed.
 117
 118 =head1 RETURN VALUES
 119
 120
 121 RAND_DRBG_new_ex() and RAND_DRBG_new() return a pointer to a DRBG instance
 122 allocated on the heap.
 123
 124 RAND_DRBG_set(),
 125 RAND_DRBG_instantiate(), and
 126 RAND_DRBG_uninstantiate()
 127 return 1 on success, and 0 on failure.
 128
 129 RAND_DRBG_verify_zeroization() returns 1 if the DRBG state is current zeroed,
 130 and 0 if not.
 131
 132 RAND_DRBG_free() does not return a value.
 133
 134 =head1 NOTES
 135
 136 The DRBG design supports I<chaining>, which means that a DRBG instance can
 137 use another B<parent> DRBG instance instead of the default entropy source
 138 to obtain fresh random input for reseeding, provided that B<parent> DRBG
 139 instance was properly instantiated, either from a trusted entropy source,
 140 or from yet another parent DRBG instance.
 141 For a detailed description of the reseeding process, see L<RAND_DRBG(7)>.
 142
 143 The default DRBG type and flags are applied only during creation of a DRBG
 144 instance.
 145 To ensure that they are applied to the global and thread-local DRBG instances
 146 (<master>, resp. <public> and <private>), it is necessary to call
 147 RAND_DRBG_set_defaults() before creating any thread and before calling any
 148 cryptographic routines that obtain random data directly or indirectly.
 149
 150 =head1 SEE ALSO
 151
 152 L<RAND_DRBG_generate(3)>,
 153 L<RAND_DRBG(7)>
 154
 155 =head1 HISTORY
 156
 157 The RAND_DRBG_set() function was deprecated in OpenSSL 3.0.
 158
 159 The RAND_DRBG functions were added in OpenSSL 1.1.1.
 160
 161 =head1 COPYRIGHT
 162
 163 Copyright 2017-2019 The OpenSSL Project Authors. All Rights Reserved.
 164
 165 Licensed under the Apache License 2.0 (the "License").  You may not use
 166 this file except in compliance with the License.  You can obtain a copy
 167 in the file LICENSE in the source distribution or at
 168 L<https://www.openssl.org/source/license.html>.
 169
 170 =cut