Rewrite RAND_enable_fork_unsafe_buffering documentation

The docs still describe the old implementation, but our PRNG has changed
drastically since then.

Change-Id: I51c34833a364a1d6bd70cf5d3b6cfb87b4aa06e7
Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/67569
Commit-Queue: Adam Langley <agl@google.com>
Reviewed-by: Adam Langley <agl@google.com>
Auto-Submit: David Benjamin <davidben@google.com>
Commit-Queue: David Benjamin <davidben@google.com>

1 files changed, 19 insertions, 10 deletions

diff --git a/include/openssl/rand.h b/include/openssl/rand.h
index 215798e..4154ef4 100644
--- a/include/openssl/rand.h
+++ b/include/openssl/rand.h
@@ -33,20 +33,29 @@ OPENSSL_EXPORT int RAND_bytes(uint8_t *buf, size_t len);
 // Obscure functions.
 
 #if !defined(OPENSSL_WINDOWS)
-// RAND_enable_fork_unsafe_buffering enables efficient buffered reading of
-// /dev/urandom. It adds an overhead of a few KB of memory per thread. It must
-// be called before the first call to |RAND_bytes|.
+// RAND_enable_fork_unsafe_buffering indicates that clones of the address space,
+// e.g. via |fork|, will never call into BoringSSL. It may be used to disable
+// BoringSSL's more expensive fork-safety measures. However, calling this
+// function and then using BoringSSL across |fork| calls will leak secret keys.
+// |fd| must be -1.
 //
-// |fd| must be -1. We no longer support setting the file descriptor with this
-// function.
+// WARNING: This function affects BoringSSL for the entire address space. Thus
+// this function should never be called by library code, only by code with
+// global knowledge of the application's use of BoringSSL.
 //
-// It has an unusual name because the buffer is unsafe across calls to |fork|.
-// Hence, this function should never be called by libraries.
+// Do not use this function unless a performance issue was measured with the
+// default behavior. BoringSSL can efficiently detect forks on most platforms,
+// in which case this function is a no-op and is unnecessary. In particular,
+// Linux kernel versions 4.14 or later provide |MADV_WIPEONFORK|. Future
+// versions of BoringSSL will remove this functionality when older kernels are
+// sufficiently rare.
+//
+// This function has an unusual name because it historically controlled internal
+// buffers, but no longer does.
 OPENSSL_EXPORT void RAND_enable_fork_unsafe_buffering(int fd);
 
-// RAND_disable_fork_unsafe_buffering disables efficient buffered reading of
-// /dev/urandom, causing BoringSSL to always draw entropy on every request
-// for random bytes.
+// RAND_disable_fork_unsafe_buffering restores BoringSSL's default fork-safety
+// protections. See also |RAND_enable_fork_unsafe_buffering|.
 OPENSSL_EXPORT void RAND_disable_fork_unsafe_buffering(void);
 #endif