1*1dcdf01fSchristos=pod 2*1dcdf01fSchristos 3*1dcdf01fSchristos=head1 NAME 4*1dcdf01fSchristos 5*1dcdf01fSchristosRAND 6*1dcdf01fSchristos- the OpenSSL random generator 7*1dcdf01fSchristos 8*1dcdf01fSchristos=head1 DESCRIPTION 9*1dcdf01fSchristos 10*1dcdf01fSchristosRandom numbers are a vital part of cryptography, they are needed to provide 11*1dcdf01fSchristosunpredictability for tasks like key generation, creating salts, and many more. 12*1dcdf01fSchristosSoftware-based generators must be seeded with external randomness before they 13*1dcdf01fSchristoscan be used as a cryptographically-secure pseudo-random number generator 14*1dcdf01fSchristos(CSPRNG). 15*1dcdf01fSchristosThe availability of common hardware with special instructions and 16*1dcdf01fSchristosmodern operating systems, which may use items such as interrupt jitter 17*1dcdf01fSchristosand network packet timings, can be reasonable sources of seeding material. 18*1dcdf01fSchristos 19*1dcdf01fSchristosOpenSSL comes with a default implementation of the RAND API which is based on 20*1dcdf01fSchristosthe deterministic random bit generator (DRBG) model as described in 21*1dcdf01fSchristos[NIST SP 800-90A Rev. 1]. The default random generator will initialize 22*1dcdf01fSchristosautomatically on first use and will be fully functional without having 23*1dcdf01fSchristosto be initialized ('seeded') explicitly. 24*1dcdf01fSchristosIt seeds and reseeds itself automatically using trusted random sources 25*1dcdf01fSchristosprovided by the operating system. 26*1dcdf01fSchristos 27*1dcdf01fSchristosAs a normal application developer, you do not have to worry about any details, 28*1dcdf01fSchristosjust use L<RAND_bytes(3)> to obtain random data. 29*1dcdf01fSchristosHaving said that, there is one important rule to obey: Always check the error 30*1dcdf01fSchristosreturn value of L<RAND_bytes(3)> and do not take randomness for granted. 31*1dcdf01fSchristosAlthough (re-)seeding is automatic, it can fail because no trusted random source 32*1dcdf01fSchristosis available or the trusted source(s) temporarily fail to provide sufficient 33*1dcdf01fSchristosrandom seed material. 34*1dcdf01fSchristosIn this case the CSPRNG enters an error state and ceases to provide output, 35*1dcdf01fSchristosuntil it is able to recover from the error by reseeding itself. 36*1dcdf01fSchristosFor more details on reseeding and error recovery, see L<RAND_DRBG(7)>. 37*1dcdf01fSchristos 38*1dcdf01fSchristosFor values that should remain secret, you can use L<RAND_priv_bytes(3)> 39*1dcdf01fSchristosinstead. 40*1dcdf01fSchristosThis method does not provide 'better' randomness, it uses the same type of CSPRNG. 41*1dcdf01fSchristosThe intention behind using a dedicated CSPRNG exclusively for private 42*1dcdf01fSchristosvalues is that none of its output should be visible to an attacker (e.g., 43*1dcdf01fSchristosused as salt value), in order to reveal as little information as 44*1dcdf01fSchristospossible about its internal state, and that a compromise of the "public" 45*1dcdf01fSchristosCSPRNG instance will not affect the secrecy of these private values. 46*1dcdf01fSchristos 47*1dcdf01fSchristosIn the rare case where the default implementation does not satisfy your special 48*1dcdf01fSchristosrequirements, there are two options: 49*1dcdf01fSchristos 50*1dcdf01fSchristos=over 2 51*1dcdf01fSchristos 52*1dcdf01fSchristos=item * 53*1dcdf01fSchristos 54*1dcdf01fSchristosReplace the default RAND method by your own RAND method using 55*1dcdf01fSchristosL<RAND_set_rand_method(3)>. 56*1dcdf01fSchristos 57*1dcdf01fSchristos=item * 58*1dcdf01fSchristos 59*1dcdf01fSchristosModify the default settings of the OpenSSL RAND method by modifying the security 60*1dcdf01fSchristosparameters of the underlying DRBG, which is described in detail in L<RAND_DRBG(7)>. 61*1dcdf01fSchristos 62*1dcdf01fSchristos=back 63*1dcdf01fSchristos 64*1dcdf01fSchristosChanging the default random generator or its default parameters should be necessary 65*1dcdf01fSchristosonly in exceptional cases and is not recommended, unless you have a profound knowledge 66*1dcdf01fSchristosof cryptographic principles and understand the implications of your changes. 67*1dcdf01fSchristos 68*1dcdf01fSchristos=head1 SEE ALSO 69*1dcdf01fSchristos 70*1dcdf01fSchristosL<RAND_add(3)>, 71*1dcdf01fSchristosL<RAND_bytes(3)>, 72*1dcdf01fSchristosL<RAND_priv_bytes(3)>, 73*1dcdf01fSchristosL<RAND_get_rand_method(3)>, 74*1dcdf01fSchristosL<RAND_set_rand_method(3)>, 75*1dcdf01fSchristosL<RAND_OpenSSL(3)>, 76*1dcdf01fSchristosL<RAND_DRBG(7)> 77*1dcdf01fSchristos 78*1dcdf01fSchristos=head1 COPYRIGHT 79*1dcdf01fSchristos 80*1dcdf01fSchristosCopyright 2018-2019 The OpenSSL Project Authors. All Rights Reserved. 81*1dcdf01fSchristos 82*1dcdf01fSchristosLicensed under the OpenSSL license (the "License"). You may not use 83*1dcdf01fSchristosthis file except in compliance with the License. You can obtain a copy 84*1dcdf01fSchristosin the file LICENSE in the source distribution or at 85*1dcdf01fSchristosL<https://www.openssl.org/source/license.html>. 86*1dcdf01fSchristos 87*1dcdf01fSchristos=cut 88