doc/man3/RAND_DRBG_new.pod

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