secure/lib/libcrypto/man/RAND_DRBG_new.3

   1 .\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
   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 .if !\nF .nr F 0
  58 .if \nF>0 \{\
  59 .    de IX
  60 .    tm Index:\\$1\t\\n%\t"\\$2"
  61 ..
  62 .    if !\nF==2 \{\
  63 .        nr % 0
  64 .        nr F 2
  65 .    \}
  66 .\}
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "RAND_DRBG_NEW 3"
 132 .TH RAND_DRBG_NEW 3 "2018-11-20" "1.1.1a" "OpenSSL"
 133 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 134 .\" way too many mistakes in technical documents.
 135 .if n .ad l
 136 .nh
 137 .SH "NAME"
 138 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
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 .Vb 1
 142 \& #include <openssl/rand_drbg.h>
 143 \&
 144 \&
 145 \& RAND_DRBG *RAND_DRBG_new(int type,
 146 \&                          unsigned int flags,
 147 \&                          RAND_DRBG *parent);
 148 \&
 149 \& RAND_DRBG *RAND_DRBG_secure_new(int type,
 150 \&                                 unsigned int flags,
 151 \&                                 RAND_DRBG *parent);
 152 \&
 153 \& int RAND_DRBG_set(RAND_DRBG *drbg,
 154 \&                   int type, unsigned int flags);
 155 \&
 156 \& int RAND_DRBG_set_defaults(int type, unsigned int flags);
 157 \&
 158 \& int RAND_DRBG_instantiate(RAND_DRBG *drbg,
 159 \&                           const unsigned char *pers, size_t perslen);
 160 \&
 161 \& int RAND_DRBG_uninstantiate(RAND_DRBG *drbg);
 162 \&
 163 \& void RAND_DRBG_free(RAND_DRBG *drbg);
 164 .Ve
 165 .SH "DESCRIPTION"
 166 .IX Header "DESCRIPTION"
 167 \&\fIRAND_DRBG_new()\fR and \fIRAND_DRBG_secure_new()\fR
 168 create a new \s-1DRBG\s0 instance of the given \fBtype\fR, allocated from the heap resp.
 169 the secure heap
 170 (using \fIOPENSSL_zalloc()\fR resp. \fIOPENSSL_secure_zalloc()\fR).
 171 .PP
 172 \&\fIRAND_DRBG_set()\fR initializes the \fBdrbg\fR with the given \fBtype\fR and \fBflags\fR.
 173 .PP
 174 \&\fIRAND_DRBG_set_defaults()\fR sets the default \fBtype\fR and \fBflags\fR for new \s-1DRBG\s0
 175 instances.
 176 .PP
 177 Currently, all \s-1DRBG\s0 types are based on AES-CTR, so \fBtype\fR can be one of the
 178 following values: NID_aes_128_ctr, NID_aes_192_ctr, NID_aes_256_ctr.
 179 Before the \s-1DRBG\s0 can be used to generate random bits, it is necessary to set
 180 its type and to instantiate it.
 181 .PP
 182 The optional \fBflags\fR argument specifies a set of bit flags which can be
 183 joined using the | operator. Currently, the only flag is
 184 \&\s-1RAND_DRBG_FLAG_CTR_NO_DF,\s0 which disables the use of a the derivation function
 185 ctr_df. For an explanation, see [\s-1NIST SP 800\-90A\s0 Rev. 1].
 186 .PP
 187 If a \fBparent\fR instance is specified then this will be used instead of
 188 the default entropy source for reseeding the \fBdrbg\fR. It is said that the
 189 \&\fBdrbg\fR is \fIchained\fR to its \fBparent\fR.
 190 For more information, see the \s-1NOTES\s0 section.
 191 .PP
 192 \&\fIRAND_DRBG_instantiate()\fR
 193 seeds the \fBdrbg\fR instance using random input from trusted entropy sources.
 194 Optionally, a personalization string \fBpers\fR of length \fBperslen\fR can be
 195 specified.
 196 To omit the personalization string, set \fBpers\fR=NULL and \fBperslen\fR=0;
 197 .PP
 198 \&\fIRAND_DRBG_uninstantiate()\fR
 199 clears the internal state of the \fBdrbg\fR and puts it back in the
 200 uninstantiated state.
 201 .SH "RETURN VALUES"
 202 .IX Header "RETURN VALUES"
 203 \&\fIRAND_DRBG_new()\fR and \fIRAND_DRBG_secure_new()\fR return a pointer to a \s-1DRBG\s0
 204 instance allocated on the heap, resp. secure heap.
 205 .PP
 206 \&\fIRAND_DRBG_set()\fR,
 207 \&\fIRAND_DRBG_instantiate()\fR, and
 208 \&\fIRAND_DRBG_uninstantiate()\fR
 209 return 1 on success, and 0 on failure.
 210 .PP
 211 \&\fIRAND_DRBG_free()\fR does not return a value.
 212 .SH "NOTES"
 213 .IX Header "NOTES"
 214 The \s-1DRBG\s0 design supports \fIchaining\fR, which means that a \s-1DRBG\s0 instance can
 215 use another \fBparent\fR \s-1DRBG\s0 instance instead of the default entropy source
 216 to obtain fresh random input for reseeding, provided that \fBparent\fR \s-1DRBG\s0
 217 instance was properly instantiated, either from a trusted entropy source,
 218 or from yet another parent \s-1DRBG\s0 instance.
 219 For a detailed description of the reseeding process, see \s-1\fIRAND_DRBG\s0\fR\|(7).
 220 .PP
 221 The default \s-1DRBG\s0 type and flags are applied only during creation of a \s-1DRBG\s0
 222 instance.
 223 To ensure that they are applied to the global and thread-local \s-1DRBG\s0 instances
 224 (<master>, resp. <public> and <private>), it is necessary to call
 225 \&\fIRAND_DRBG_set_defaults()\fR before creating any thread and before calling any
 226 cryptographic routines that obtain random data directly or indirectly.
 227 .SH "HISTORY"
 228 .IX Header "HISTORY"
 229 The \s-1RAND_DRBG\s0 functions were added in OpenSSL 1.1.1.
 230 .SH "SEE ALSO"
 231 .IX Header "SEE ALSO"
 232 \&\fIOPENSSL_zalloc\fR\|(3),
 233 \&\fIOPENSSL_secure_zalloc\fR\|(3),
 234 \&\fIRAND_DRBG_generate\fR\|(3),
 235 \&\s-1\fIRAND_DRBG\s0\fR\|(7)
 236 .SH "COPYRIGHT"
 237 .IX Header "COPYRIGHT"
 238 Copyright 2017\-2018 The OpenSSL Project Authors. All Rights Reserved.
 239 .PP
 240 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 241 this file except in compliance with the License.  You can obtain a copy
 242 in the file \s-1LICENSE\s0 in the source distribution or at
 243 <https://www.openssl.org/source/license.html>.