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