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