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