secure/lib/libcrypto/man/man3/RAND_DRBG_new.3

   1 .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "RAND_DRBG_NEW 3"
 136 .TH RAND_DRBG_NEW 3 "2022-05-03" "1.1.1o" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 RAND_DRBG_new, RAND_DRBG_secure_new, RAND_DRBG_set, RAND_DRBG_set_defaults, RAND_DRBG_instantiate, RAND_DRBG_uninstantiate, RAND_DRBG_free \&\- initialize and cleanup a RAND_DRBG instance
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/rand_drbg.h>
 147 \&
 148 \&
 149 \& RAND_DRBG *RAND_DRBG_new(int type,
 150 \&                          unsigned int flags,
 151 \&                          RAND_DRBG *parent);
 152 \&
 153 \& RAND_DRBG *RAND_DRBG_secure_new(int type,
 154 \&                                 unsigned int flags,
 155 \&                                 RAND_DRBG *parent);
 156 \&
 157 \& int RAND_DRBG_set(RAND_DRBG *drbg,
 158 \&                   int type, unsigned int flags);
 159 \&
 160 \& int RAND_DRBG_set_defaults(int type, unsigned int flags);
 161 \&
 162 \& int RAND_DRBG_instantiate(RAND_DRBG *drbg,
 163 \&                           const unsigned char *pers, size_t perslen);
 164 \&
 165 \& int RAND_DRBG_uninstantiate(RAND_DRBG *drbg);
 166 \&
 167 \& void RAND_DRBG_free(RAND_DRBG *drbg);
 168 .Ve
 169 .SH "DESCRIPTION"
 170 .IX Header "DESCRIPTION"
 171 \&\fBRAND_DRBG_new()\fR and \fBRAND_DRBG_secure_new()\fR
 172 create a new \s-1DRBG\s0 instance of the given \fBtype\fR, allocated from the heap resp.
 173 the secure heap
 174 (using \fBOPENSSL_zalloc()\fR resp. \fBOPENSSL_secure_zalloc()\fR).
 175 .PP
 176 \&\fBRAND_DRBG_set()\fR initializes the \fBdrbg\fR with the given \fBtype\fR and \fBflags\fR.
 177 .PP
 178 \&\fBRAND_DRBG_set_defaults()\fR sets the default \fBtype\fR and \fBflags\fR for new \s-1DRBG\s0
 179 instances.
 180 .PP
 181 Currently, all \s-1DRBG\s0 types are based on AES-CTR, so \fBtype\fR can be one of the
 182 following values: NID_aes_128_ctr, NID_aes_192_ctr, NID_aes_256_ctr.
 183 Before the \s-1DRBG\s0 can be used to generate random bits, it is necessary to set
 184 its type and to instantiate it.
 185 .PP
 186 The optional \fBflags\fR argument specifies a set of bit flags which can be
 187 joined using the | operator. Currently, the only flag is
 188 \&\s-1RAND_DRBG_FLAG_CTR_NO_DF,\s0 which disables the use of the derivation function
 189 ctr_df. For an explanation, see [\s-1NIST SP 800\-90A\s0 Rev. 1].
 190 .PP
 191 If a \fBparent\fR instance is specified then this will be used instead of
 192 the default entropy source for reseeding the \fBdrbg\fR. It is said that the
 193 \&\fBdrbg\fR is \fIchained\fR to its \fBparent\fR.
 194 For more information, see the \s-1NOTES\s0 section.
 195 .PP
 196 \&\fBRAND_DRBG_instantiate()\fR
 197 seeds the \fBdrbg\fR instance using random input from trusted entropy sources.
 198 Optionally, a personalization string \fBpers\fR of length \fBperslen\fR can be
 199 specified.
 200 To omit the personalization string, set \fBpers\fR=NULL and \fBperslen\fR=0;
 201 .PP
 202 \&\fBRAND_DRBG_uninstantiate()\fR
 203 clears the internal state of the \fBdrbg\fR and puts it back in the
 204 uninstantiated state.
 205 .SH "RETURN VALUES"
 206 .IX Header "RETURN VALUES"
 207 \&\fBRAND_DRBG_new()\fR and \fBRAND_DRBG_secure_new()\fR return a pointer to a \s-1DRBG\s0
 208 instance allocated on the heap, resp. secure heap.
 209 .PP
 210 \&\fBRAND_DRBG_set()\fR,
 211 \&\fBRAND_DRBG_instantiate()\fR, and
 212 \&\fBRAND_DRBG_uninstantiate()\fR
 213 return 1 on success, and 0 on failure.
 214 .PP
 215 \&\fBRAND_DRBG_free()\fR does not return a value.
 216 .SH "NOTES"
 217 .IX Header "NOTES"
 218 The \s-1DRBG\s0 design supports \fIchaining\fR, which means that a \s-1DRBG\s0 instance can
 219 use another \fBparent\fR \s-1DRBG\s0 instance instead of the default entropy source
 220 to obtain fresh random input for reseeding, provided that \fBparent\fR \s-1DRBG\s0
 221 instance was properly instantiated, either from a trusted entropy source,
 222 or from yet another parent \s-1DRBG\s0 instance.
 223 For a detailed description of the reseeding process, see \s-1\fBRAND_DRBG\s0\fR\|(7).
 224 .PP
 225 The default \s-1DRBG\s0 type and flags are applied only during creation of a \s-1DRBG\s0
 226 instance.
 227 To ensure that they are applied to the global and thread-local \s-1DRBG\s0 instances
 228 (<master>, resp. <public> and <private>), it is necessary to call
 229 \&\fBRAND_DRBG_set_defaults()\fR before creating any thread and before calling any
 230 cryptographic routines that obtain random data directly or indirectly.
 231 .SH "SEE ALSO"
 232 .IX Header "SEE ALSO"
 233 \&\fBOPENSSL_zalloc\fR\|(3),
 234 \&\fBOPENSSL_secure_zalloc\fR\|(3),
 235 \&\fBRAND_DRBG_generate\fR\|(3),
 236 \&\s-1\fBRAND_DRBG\s0\fR\|(7)
 237 .SH "HISTORY"
 238 .IX Header "HISTORY"
 239 The \s-1RAND_DRBG\s0 functions were added in OpenSSL 1.1.1.
 240 .SH "COPYRIGHT"
 241 .IX Header "COPYRIGHT"
 242 Copyright 2017\-2020 The OpenSSL Project Authors. All Rights Reserved.
 243 .PP
 244 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 245 this file except in compliance with the License.  You can obtain a copy
 246 in the file \s-1LICENSE\s0 in the source distribution or at
 247 <https://www.openssl.org/source/license.html>.