man: clarify the 'random number generator must be seeded' requirement

[oweals/openssl.git] / doc / man7 / RAND.pod

diff --git a/doc/man7/RAND.pod b/doc/man7/RAND.pod
index 971b3cdb161287a62c6b64191da579ddc8fa53d6..bc6db303c2f07a0e436cb3dd4b8fe5be26f2c36c 100644 (file)
--- a/doc/man7/RAND.pod
+++ b/doc/man7/RAND.pod
@@ -28,6 +28,12 @@ As a normal application developer, you do not have to worry about any details,
 just use L<RAND_bytes(3)> to obtain random data.
 Having said that, there is one important rule to obey: Always check the error
 return value of L<RAND_bytes(3)> and do not take randomness for granted.
+Although (re-)seeding is automatic, it can fail because no trusted random source
+is available or the trusted source(s) temporarily fail to provide sufficient
+random seed material.
+In this case the CSPRNG enters an error state and ceases to provide output,
+until it is able to recover from the error by reseeding itself.
+For more details on reseeding and error recovery, see L<RAND_DRBG(7)>.
 
 For values that should remain secret, you can use L<RAND_priv_bytes(3)>
 instead.