add an opt-in less-safe-getrandom-custom feature

This Cargo feature treats a user-provided `getrandom` implementation as
a secure random number generator (`SecureRandom`). The feature only has
effect on targets not supported by `getrandom`.

I agree to license my contributions to each file under the terms given
at the top of each file I changed.

Cargo.toml

@@ -197,6 +197,7 @@ cc = { version = "1.0.83", default-features = false }
 default = ["alloc", "dev_urandom_fallback"]
 alloc = []
 dev_urandom_fallback = []
+less-safe-getrandom-custom = ["getrandom/custom"]
 slow_tests = []
 std = ["alloc"]
 unstable-testing-arm-no-hw = []

src/lib.rs

@@ -22,6 +22,14 @@
 //!     <th>Description
 //! <tr><td><code>alloc (default)</code>
 //!     <td>Enable features that require use of the heap, RSA in particular.
+//! <tr><td><code>less-safe-getrandom-custom</code>
+//!     <td>Treat a user-provided ("custom") <code>getrandom</code>
+//!         implementation as a secure random number generator (see
+//!         <code>SecureRandom</code>). Only has effect on targets
+//!         <strong>not</strong> supported by <code>getrandom</code>.
+//!         See <a href="https://docs.rs/getrandom/0.2.10/getrandom/macro.register_custom_getrandom.html">
+//!             <code>register_custom_getrandom</code>
+//!         </a> for details.
 //! <tr><td><code>std</code>
 //!     <td>Enable features that use libstd, in particular
 //!         <code>std::error::Error</code> integration. Implies `alloc`.

src/rand.rs

@@ -125,6 +125,10 @@ impl crate::sealed::Sealed for SystemRandom {}
 // system's) CSPRNG. Avoid using it on targets where it uses the `rdrand`
 // implementation.
 #[cfg(any(
+    // NOTE `getrandom`'s (v0.2.10) docs state that a custom implementation will
+    // NOT override the implementation of supported targets, like the ones
+    // listed below.
+    feature = "less-safe-getrandom-custom",
     target_os = "aix",
     target_os = "android",
     target_os = "dragonfly",