Debian Codegraph @

upstream/debian-unstable/man7/RAND.7ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "RAND 7SSL"
58 .TH RAND 7SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 RAND
65 \&\- the OpenSSL random generator
66 .SH DESCRIPTION
67 .IX Header "DESCRIPTION"
68 Random numbers are a vital part of cryptography, they are needed to provide
69 unpredictability for tasks like key generation, creating salts, and many more.
70 Software-based generators must be seeded with external randomness before they
71 can be used as a cryptographically-secure pseudo-random number generator
72 (CSPRNG).
73 The availability of common hardware with special instructions and
74 modern operating systems, which may use items such as interrupt jitter
75 and network packet timings, can be reasonable sources of seeding material.
76 .PP
77 OpenSSL comes with a default implementation of the RAND API which is based on
78 the deterministic random bit generator (DRBG) model as described in
79 [NIST SP 800\-90A Rev. 1]. The default random generator will initialize
80 automatically on first use and will be fully functional without having
81 to be initialized ('seeded') explicitly.
82 It seeds and reseeds itself automatically using trusted random sources
83 provided by the operating system.
84 .PP
85 As a normal application developer, you do not have to worry about any details,
86 just use \fBRAND_bytes\fR\|(3) to obtain random data.
87 Having said that, there is one important rule to obey: Always check the error
88 return value of \fBRAND_bytes\fR\|(3) and do not take randomness for granted.
89 Although (re\-)seeding is automatic, it can fail because no trusted random source
90 is available or the trusted source(s) temporarily fail to provide sufficient
91 random seed material.
92 In this case the CSPRNG enters an error state and ceases to provide output,
93 until it is able to recover from the error by reseeding itself.
94 For more details on reseeding and error recovery, see \fBEVP_RAND\fR\|(7).
95 .PP
96 For values that should remain secret, you can use \fBRAND_priv_bytes\fR\|(3)
97 instead.
98 This method does not provide 'better' randomness, it uses the same type of
99 CSPRNG.
100 The intention behind using a dedicated CSPRNG exclusively for private
101 values is that none of its output should be visible to an attacker (e.g.,
102 used as salt value), in order to reveal as little information as
103 possible about its internal state, and that a compromise of the "public"
104 CSPRNG instance will not affect the secrecy of these private values.
105 .PP
106 In the rare case where the default implementation does not satisfy your special
107 requirements, the default RAND internals can be replaced by your own
108 \&\fBEVP_RAND\fR\|(3) objects.
109 .PP
110 Changing the default random generator should be necessary
111 only in exceptional cases and is not recommended, unless you have a profound
112 knowledge of cryptographic principles and understand the implications of your
113 changes.
114 .PP
115 Finally, it is possible for a provider to bypass the default RAND setup for
116 \&\fBRAND_bytes\fR\|(3) and associated functions. A provider can be specified as the
117 single randomness source via the \fBRAND_set1_random_provider\fR\|(3) function or via
118 configuration using the \fBrandom_provider\fR option in \fBconfig\fR\|(5). Once specified,
119 the nominated provider will be used directly when calling the \fBRAND_bytes\fR\|(3)
120 family of functions.
121 .SH "DEFAULT SETUP"
122 .IX Header "DEFAULT SETUP"
123 The default OpenSSL RAND method is based on the EVP_RAND deterministic random
124 bit generator (DRBG) classes.
125 A DRBG is a certain type of cryptographically-secure pseudo-random
126 number generator (CSPRNG), which is described in [NIST SP 800\-90A Rev. 1].
127 .SH "SEE ALSO"
128 .IX Header "SEE ALSO"
129 \&\fBRAND_bytes\fR\|(3),
130 \&\fBRAND_priv_bytes\fR\|(3),
131 \&\fBEVP_RAND\fR\|(3),
132 \&\fBRAND_get0_primary\fR\|(3),
133 \&\fBconfig\fR\|(5),
134 \&\fBEVP_RAND\fR\|(7),
135 \&\fBRAND_set1_random_provider\fR\|(3).
136 .SH COPYRIGHT
137 .IX Header "COPYRIGHT"
138 Copyright 2018\-2025 The OpenSSL Project Authors. All Rights Reserved.
139 .PP
140 Licensed under the Apache License 2.0 (the "License"). You may not use
141 this file except in compliance with the License. You can obtain a copy
142 in the file LICENSE in the source distribution or at
143 <https://www.openssl.org/source/license.html>.