1RAND(7ossl) OpenSSL RAND(7ossl)
2
6 RAND - the OpenSSL random generator
7
9 Random numbers are a vital part of cryptography, they are needed to
10 provide unpredictability for tasks like key generation, creating salts,
11 and many more. Software-based generators must be seeded with external
12 randomness before they can be used as a cryptographically-secure
13 pseudo-random number generator (CSPRNG). The availability of common
14 hardware with special instructions and modern operating systems, which
15 may use items such as interrupt jitter and network packet timings, can
16 be reasonable sources of seeding material.
17 OpenSSL comes with a default implementation of the RAND API which is
19 based on the deterministic random bit generator (DRBG) model as
20 described in [NIST SP 800-90A Rev. 1]. The default random generator
21 will initialize automatically on first use and will be fully functional
22 without having to be initialized ('seeded') explicitly. It seeds and
23 reseeds itself automatically using trusted random sources provided by
24 the operating system.
25 As a normal application developer, you do not have to worry about any
27 details, just use RAND_bytes(3) to obtain random data. Having said
28 that, there is one important rule to obey: Always check the error
29 return value of RAND_bytes(3) and do not take randomness for granted.
30 Although (re-)seeding is automatic, it can fail because no trusted
31 random source is available or the trusted source(s) temporarily fail to
32 provide sufficient random seed material. In this case the CSPRNG
33 enters an error state and ceases to provide output, until it is able to
34 recover from the error by reseeding itself. For more details on
35 reseeding and error recovery, see EVP_RAND(7).
36 For values that should remain secret, you can use RAND_priv_bytes(3)
38 instead. This method does not provide 'better' randomness, it uses the
39 same type of CSPRNG. The intention behind using a dedicated CSPRNG
40 exclusively for private values is that none of its output should be
41 visible to an attacker (e.g., used as salt value), in order to reveal
42 as little information as possible about its internal state, and that a
43 compromise of the "public" CSPRNG instance will not affect the secrecy
44 of these private values.
45 In the rare case where the default implementation does not satisfy your
47 special requirements, the default RAND internals can be replaced by
48 your own EVP_RAND(3) objects.
49 Changing the default random generator should be necessary only in
51 exceptional cases and is not recommended, unless you have a profound
52 knowledge of cryptographic principles and understand the implications
53 of your changes.
54
56 The default OpenSSL RAND method is based on the EVP_RAND deterministic
57 random bit generator (DRBG) classes. A DRBG is a certain type of
58 cryptographically-secure pseudo-random number generator (CSPRNG), which
59 is described in [NIST SP 800-90A Rev. 1].
60
62 RAND_bytes(3), RAND_priv_bytes(3), EVP_RAND(3), RAND_get0_primary(3),
63 EVP_RAND(7)
64
66 Copyright 2018-2021 The OpenSSL Project Authors. All Rights Reserved.
67 Licensed under the Apache License 2.0 (the "License"). You may not use
69 this file except in compliance with the License. You can obtain a copy
70 in the file LICENSE in the source distribution or at
71 <https://www.openssl.org/source/license.html>.
723.1.1 2023-08-31 RAND(7ossl)