secure/lib/libcrypto/man/RAND_add.3

   1 .\" Automatically generated by Pod::Man 4.10 (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 .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_ADD 3"
 136 .TH RAND_ADD 3 "2019-05-28" "1.1.1c" "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_add, RAND_poll, RAND_seed, RAND_status, RAND_event, RAND_screen, RAND_keep_random_devices_open \&\- add randomness to the PRNG or get its status
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/rand.h>
 147 \&
 148 \& int RAND_status(void);
 149 \& int RAND_poll();
 150 \&
 151 \& void RAND_add(const void *buf, int num, double randomness);
 152 \& void RAND_seed(const void *buf, int num);
 153 \&
 154 \& void RAND_keep_random_devices_open(int keep);
 155 .Ve
 156 .PP
 157 Deprecated:
 158 .PP
 159 .Vb 4
 160 \& #if OPENSSL_API_COMPAT < 0x10100000L
 161 \& int RAND_event(UINT iMsg, WPARAM wParam, LPARAM lParam);
 162 \& void RAND_screen(void);
 163 \& #endif
 164 .Ve
 165 .SH "DESCRIPTION"
 166 .IX Header "DESCRIPTION"
 167 These functions can be used to seed the random generator and to check its
 168 seeded state.
 169 In general, manual (re\-)seeding of the default OpenSSL random generator
 170 (\fBRAND_OpenSSL\fR\|(3)) is not necessary (but allowed), since it does (re\-)seed
 171 itself automatically using trusted system entropy sources.
 172 This holds unless the default \s-1RAND_METHOD\s0 has been replaced or OpenSSL was
 173 built with automatic reseeding disabled, see \s-1\fBRAND\s0\fR\|(7) for more details.
 174 .PP
 175 \&\fBRAND_status()\fR indicates whether or not the random generator has been sufficiently
 176 seeded. If not, functions such as \fBRAND_bytes\fR\|(3) will fail.
 177 .PP
 178 \&\fBRAND_poll()\fR uses the system's capabilities to seed the random generator using
 179 random input obtained from polling various trusted entropy sources.
 180 The default choice of the entropy source can be modified at build time,
 181 see \s-1\fBRAND\s0\fR\|(7) for more details.
 182 .PP
 183 \&\fBRAND_add()\fR mixes the \fBnum\fR bytes at \fBbuf\fR into the internal state
 184 of the random generator.
 185 This function will not normally be needed, as mentioned above.
 186 The \fBrandomness\fR argument is an estimate of how much randomness is
 187 contained in
 188 \&\fBbuf\fR, in bytes, and should be a number between zero and \fBnum\fR.
 189 Details about sources of randomness and how to estimate their randomness
 190 can be found in the literature; for example [\s-1NIST SP 800\-90B\s0].
 191 The content of \fBbuf\fR cannot be recovered from subsequent random generator output.
 192 Applications that intend to save and restore random state in an external file
 193 should consider using \fBRAND_load_file\fR\|(3) instead.
 194 .PP
 195 \&\fBRAND_seed()\fR is equivalent to \fBRAND_add()\fR with \fBrandomness\fR set to \fBnum\fR.
 196 .PP
 197 \&\fBRAND_keep_random_devices_open()\fR is used to control file descriptor
 198 usage by the random seed sources. Some seed sources maintain open file
 199 descriptors by default, which allows such sources to operate in a
 200 \&\fBchroot\fR\|(2) jail without the associated device nodes being available. When
 201 the \fBkeep\fR argument is zero, this call disables the retention of file
 202 descriptors. Conversely, a non-zero argument enables the retention of
 203 file descriptors. This function is usually called during initialization
 204 and it takes effect immediately.
 205 .PP
 206 \&\fBRAND_event()\fR and \fBRAND_screen()\fR are equivalent to \fBRAND_poll()\fR and exist
 207 for compatibility reasons only. See \s-1HISTORY\s0 section below.
 208 .SH "RETURN VALUES"
 209 .IX Header "RETURN VALUES"
 210 \&\fBRAND_status()\fR returns 1 if the random generator has been seeded
 211 with enough data, 0 otherwise.
 212 .PP
 213 \&\fBRAND_poll()\fR returns 1 if it generated seed data, 0 otherwise.
 214 .PP
 215 \&\fBRAND_event()\fR returns \fBRAND_status()\fR.
 216 .PP
 217 The other functions do not return values.
 218 .SH "SEE ALSO"
 219 .IX Header "SEE ALSO"
 220 \&\fBRAND_bytes\fR\|(3),
 221 \&\fBRAND_egd\fR\|(3),
 222 \&\fBRAND_load_file\fR\|(3),
 223 \&\s-1\fBRAND\s0\fR\|(7)
 224 .SH "HISTORY"
 225 .IX Header "HISTORY"
 226 \&\fBRAND_event()\fR and \fBRAND_screen()\fR were deprecated in OpenSSL 1.1.0 and should
 227 not be used.
 228 .SH "COPYRIGHT"
 229 .IX Header "COPYRIGHT"
 230 Copyright 2000\-2019 The OpenSSL Project Authors. All Rights Reserved.
 231 .PP
 232 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 233 this file except in compliance with the License.  You can obtain a copy
 234 in the file \s-1LICENSE\s0 in the source distribution or at
 235 <https://www.openssl.org/source/license.html>.