diff --git a/doc/man1/rand.pod b/doc/man1/rand.pod index 5dd9e8e0a56a70fe36ca1c22e99724afc7f92920..6b6c285248cbf70c30d29cd6de0e3b462de60df9 100644 --- a/doc/man1/rand.pod +++ b/doc/man1/rand.pod @@ -18,12 +18,14 @@ I =head1 DESCRIPTION -The B command outputs I pseudo-random bytes after seeding -the random number generator once. As in other B command -line tools, PRNG seeding uses the file I<$HOME/>B<.rnd> or B<.rnd> -in addition to the files given in the B<-rand> option. A new -I<$HOME>/B<.rnd> or B<.rnd> file will be written back if enough -seeding was obtained from these sources. +This command generates I random bytes using a cryptographically +secure pseudo random number generator (CSPRNG). + +The random bytes are generated using the L function, +which provides a security level of 256 bits, provided it managed to +seed itself successfully from a trusted operating system entropy source. +Otherwise, the command will fail with a nonzero error code. +For more details, see L, L, and L. =head1 OPTIONS @@ -44,6 +46,8 @@ generator. Multiple files can be specified separated by an OS-dependent character. The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for all others. +Explicitly specifying a seed file is in general not necessary, see the +L section for more information. =item [B<-writerand file>] @@ -60,13 +64,28 @@ Show the output as a hex string. =back +=head1 NOTES + +Prior to OpenSSL 1.1.1, it was common for applications to store information +about the state of the random-number generator in a file that was loaded +at startup and rewritten upon exit. On modern operating systems, this is +generally no longer necessary as OpenSSL will seed itself from a trusted +entropy source provided by the operating system. The B<-rand> and +B<-writerand> flags are still supported for special platforms or +circumstances that might require them. + +It is generally an error to use the same seed file more than once and +every use of B<-rand> should be paired with B<-writerand>. + =head1 SEE ALSO -L +L, +L, +L =head1 COPYRIGHT -Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved. Licensed under the OpenSSL license (the "License"). You may not use this file except in compliance with the License. You can obtain a copy diff --git a/doc/man3/RAND_bytes.pod b/doc/man3/RAND_bytes.pod index e2265d170a6198c8a9359d9dedb0c95ccfe40025..63a284520581455d4e7f83b4e7ed98b212cf8a77 100644 --- a/doc/man3/RAND_bytes.pod +++ b/doc/man3/RAND_bytes.pod @@ -19,8 +19,8 @@ Deprecated: =head1 DESCRIPTION -RAND_bytes() puts B cryptographically strong pseudo-random bytes -into B. +RAND_bytes() generates B random bytes using a cryptographically +secure pseudo random generator (CSPRNG) and stores them in B. RAND_priv_bytes() has the same semantics as RAND_bytes(). It is intended to be used for generating values that should remain private. If using the @@ -31,10 +31,22 @@ and L. =head1 NOTES -Always check the error return value of RAND_bytes() and -RAND_priv_bytes() and do not take randomness for granted: an error occurs -if the CSPRNG has not been seeded with enough randomness to ensure an -unpredictable byte sequence. +By default, the OpenSSL CSPRNG supports a security level of 256 bits, provided it +was able to seed itself from a trusted entropy source. +On all major platforms supported by OpenSSL (including the Unix-like platforms +and Windows), OpenSSL is configured to automatically seed the CSPRNG on first use +using the operating systems's random generator. + +If the entropy source fails or is not available, the CSPRNG will enter an +error state and refuse to generate random bytes. For that reason, it is important +to always check the error return value of RAND_bytes() and RAND_priv_bytes() and +not take randomness for granted. + +On other platforms, there might not be a trusted entropy source available +or OpenSSL might have been explicitly configured to use different entropy sources. +If you are in doubt about the quality of the entropy source, don't hesitate to ask +your operating system vendor or post a question on GitHub or the openssl-users +mailing list. =head1 RETURN VALUES