From 2c48d16b65bb508f7ec5698fc5683d016c4d0808 Mon Sep 17 00:00:00 2001 From: Autumn Date: Mon, 1 Aug 2022 14:03:19 -0700 Subject: [PATCH] document the variation in underlying details of abstracted randomness sources --- src/lib.rs | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index c62056e55..d21a88fff 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -115,13 +115,22 @@ //! entropy yet. To avoid returning low-entropy bytes, we first poll //! `/dev/random` and only switch to `/dev/urandom` once this has succeeded. //! +//! On OpenBSD, this kind of entropy accounting isn't available, and on +//! NetBSD, blocking on it is discouraged. On these platforms, nonblocking +//! interfaces are used, even when reliable entropy may not be available. +//! On the platforms where it is used, the reliability of entropy accounting +//! itself isn't free from controversy. This library provides randomness +//! sourced according to the platform's best practices, but each platform has +//! its own limits on the grade of randomness it can promise in environments +//! with few sources of entropy. +//! //! ## Error handling //! -//! We always choose failure over returning insecure "random" bytes. In general, -//! on supported platforms, failure is highly unlikely, though not impossible. -//! If an error does occur, then it is likely that it will occur on every call to -//! `getrandom`, hence after the first successful call one can be reasonably -//! confident that no errors will occur. +//! We always choose failure over returning known insecure "random" bytes. In +//! general, on supported platforms, failure is highly unlikely, though not +//! impossible. If an error does occur, then it is likely that it will occur +//! on every call to `getrandom`, hence after the first successful call one +//! can be reasonably confident that no errors will occur. //! //! [1]: http://man7.org/linux/man-pages/man2/getrandom.2.html //! [2]: http://man7.org/linux/man-pages/man4/urandom.4.html