Buffer reads of urandom, if you promise no forking.
Callers that lack hardware random may obtain a speed improvement by
calling |RAND_enable_fork_unsafe_buffering|, which enables a
thread-local buffer around reads from /dev/urandom.
Change-Id: I46e675d1679b20434dd520c58ece0f888f38a241
Reviewed-on: https://boringssl-review.googlesource.com/5792
Reviewed-by: Adam Langley <agl@google.com>
diff --git a/include/openssl/rand.h b/include/openssl/rand.h
index 335c76e..de1bd8d 100644
--- a/include/openssl/rand.h
+++ b/include/openssl/rand.h
@@ -40,11 +40,26 @@
* randomness rather opening /dev/urandom internally. The caller retains
* ownership of |fd| and is at liberty to close it at any time. This is useful
* if, due to a sandbox, /dev/urandom isn't available. If used, it must be
- * called before |RAND_bytes| is called in the current address space.
+ * called before the first call to |RAND_bytes|, and it is mutually exclusive
+ * with |RAND_enable_fork_unsafe_buffering|.
*
* |RAND_set_urandom_fd| does not buffer any entropy, so it is safe to call
- * |fork| between |RAND_set_urandom_fd| and the first call to |RAND_bytes|. */
+ * |fork| at any time after calling |RAND_set_urandom_fd|. */
OPENSSL_EXPORT void RAND_set_urandom_fd(int fd);
+
+/* 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| and it is mutually exclusive
+ * with calls to |RAND_set_urandom_fd|.
+ *
+ * If |fd| is non-negative then a copy of |fd| will be used rather than opening
+ * /dev/urandom internally. Like |RAND_set_urandom_fd|, the caller retains
+ * ownership of |fd|. If |fd| is negative then /dev/urandom will be opened and
+ * any error from open(2) crashes the address space.
+ *
+ * It has an unusual name because the buffer is unsafe across calls to |fork|.
+ * Hence, this function should never be called by libraries. */
+OPENSSL_EXPORT void RAND_enable_fork_unsafe_buffering(int fd);
#endif
