From 042af70f643a72530355cb97cda573d99185399a Mon Sep 17 00:00:00 2001 From: Diggory Hardy Date: Tue, 28 Jan 2025 09:06:37 +0000 Subject: [PATCH 1/7] README: reword "not a cryptography library" --- README.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 740807a9669..bf813f8c5e8 100644 --- a/README.md +++ b/README.md @@ -39,12 +39,11 @@ Rand **is not**: not simplicity. If you prefer a small-and-simple library, there are alternatives including [fastrand](https://crates.io/crates/fastrand) and [oorandom](https://crates.io/crates/oorandom). -- A cryptography library. Rand provides functionality for generating - unpredictable random data (potentially applicable depending on requirements) - but does not provide high-level cryptography functionality. - -Rand is a community project and cannot provide legally-binding guarantees of -security. +- A cryptography library. `rand` is a community project and cannot provide + legally-binding guarantees of security. `rand` does not provide high-level + cryptographic functionality. Users are expected to determine for themselves + whether `rand`'s functionality meets their own security requirements. + For more, see [SECURITY.md](SECURITY.md). Documentation: From 765e5d9cdbd59f9a36811e9cdb165ebd03d8e3d2 Mon Sep 17 00:00:00 2001 From: Diggory Hardy Date: Thu, 30 Jan 2025 07:56:03 +0000 Subject: [PATCH 2/7] Update README on WASM --- README.md | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index bf813f8c5e8..3f209fd59d3 100644 --- a/README.md +++ b/README.md @@ -96,16 +96,13 @@ Many (but not all) algorithms are intended to have reproducible output. Read mor The Rand library supports a variety of CPU architectures. Platform integration is outsourced to [getrandom]. -### WASM support - -Seeding entropy from OS on WASM target `wasm32-unknown-unknown` is not -*automatically* supported by `rand` or `getrandom`. If you are fine with -seeding the generator manually, you can disable the `os_rng` feature -and use the methods on the `SeedableRng` trait. To enable seeding from OS, -either use a different target such as `wasm32-wasi` or add a direct -dependency on [getrandom] with the `js` feature (if the target supports -JavaScript). See -[getrandom#WebAssembly support](https://docs.rs/getrandom/latest/getrandom/#webassembly-support). +### WebAssembly support + +The [WASI](https://github.com/WebAssembly/WASI/tree/main) and Emscripten +targets are directly supported. The `wasm32-unknown-unknown` target is not +*automatically* supported. To enable support for this target, refer to the +[`getrandom` documentation for WebAssembly](https://docs.rs/getrandom/latest/getrandom/#webassembly-support). +Alternatively, the `os_rng` feature may be disabled. # License From 0d153338f62dd824b85997a7ada6f83456a1a500 Mon Sep 17 00:00:00 2001 From: Diggory Hardy Date: Thu, 30 Jan 2025 09:11:33 +0000 Subject: [PATCH 3/7] Update note in README --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 3f209fd59d3..530100f5615 100644 --- a/README.md +++ b/README.md @@ -39,11 +39,11 @@ Rand **is not**: not simplicity. If you prefer a small-and-simple library, there are alternatives including [fastrand](https://crates.io/crates/fastrand) and [oorandom](https://crates.io/crates/oorandom). -- A cryptography library. `rand` is a community project and cannot provide - legally-binding guarantees of security. `rand` does not provide high-level - cryptographic functionality. Users are expected to determine for themselves +- Primarily a cryptographic library. `rand` does provide some generators which + aim to support unpredictable value generation under certain constraints; + see [SECURITY.md](SECURITY.md) for details. + Users are expected to determine for themselves whether `rand`'s functionality meets their own security requirements. - For more, see [SECURITY.md](SECURITY.md). Documentation: From 42b22091adc3e2460c2a06240abb2ea02843fe5d Mon Sep 17 00:00:00 2001 From: Diggory Hardy Date: Thu, 30 Jan 2025 09:11:41 +0000 Subject: [PATCH 4/7] Revise SECURITY.md --- SECURITY.md | 75 ++++++++++++++++++++++++++--------------------------- 1 file changed, 37 insertions(+), 38 deletions(-) diff --git a/SECURITY.md b/SECURITY.md index 26cf7c12fc5..c04f43ce451 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -10,11 +10,14 @@ security. ### Marker traits Rand provides the marker traits `CryptoRng`, `TryCryptoRng` and -`CryptoBlockRng`. Generators implementing one of these traits and used in a way -which meets the following additional constraints: - -- Instances of seedable RNGs (those implementing `SeedableRng`) are - constructed with cryptographically secure seed values +`CryptoBlockRng`. Generators (RNGs) implementing one of these traits which are +used according to these additional constraints: + +- If the RNG implements `Default`, it may be default-constructed +- If the RNG implements `SeedableRng`, it may be constructed and seeded using + `SeedableRng::from_seed` with a cryptographically secure seed value +- If the RNG implements `SeedableRng`, it may be constructed and seeded from + another RNG which is itself cryptographically secure - The state (memory) of the RNG and its seed value are not exposed are expected to provide the following: @@ -34,48 +37,44 @@ are expected to provide the following: `OsRng` is a stateless "generator" implemented via [getrandom]. As such, it has no possible state to leak and cannot be improperly seeded. -`ThreadRng` will periodically reseed itself, thus placing an upper bound on the -number of bits of output from an instance before any advantage an attacker may -have gained through state-compromising side-channel attacks is lost. +`StdRng` is a `CryptoRng` and `SeedableRng` using a pseudo-random algorithm +selected for good security and performance qualities. Since it does not offer +reproducibility of output, its algorithm may be changed in any release version. + +`ChaCha12Rng` and `ChaCha20Rng` are selected pseudo-random generators +distributed by the `rand` project which meet the requirements of the `CryptoRng` +trait and implement `SeedableRng` with a commitment to reproducibility of +results. + +`ThreadRng` is a conveniently-packaged generator over `StdRng` offering +automatic seeding from `OsRng`, periodic reseeding and thread locality. +This random source is intended to offer a good compromise between cryptographic +security, fast generation with reasonably low memory and initialization cost +overheads, and robustness against misuse. [getrandom]: https://crates.io/crates/getrandom ### Distributions -Additionally, derivations from such an RNG (including the `Rng` trait, -implementations of the `Distribution` trait, and `seq` algorithms) should not -introduce significant bias other than that expected from the operation in -question (e.g. bias from a weighted distribution). +Methods of the `Rng` trait, functionality of the `rand::seq` module and +implementators of the `Distribution` trait are expected, while using a +cryptographically secure `CryptoRng` instance meeting the above constraints, +to not introduce significant bias to their operation beyond what would be +expected of the operation. Note that the usage of 'significant' here permits +some bias, as noted for example in the documentation of the `Uniform` +distribution. ## Supported Versions -We will attempt to uphold these premises in the following crate versions, -provided that only the latest patch version is used, and with potential -exceptions for theoretical issues without a known exploit: - -| Crate | Versions | Exceptions | -| ----- | -------- | ---------- | -| `rand` | 0.8 | | -| `rand` | 0.7 | | -| `rand` | 0.5, 0.6 | Jitter | -| `rand` | 0.4 | Jitter, ISAAC | -| `rand_core` | 0.2 - 0.6 | | -| `rand_chacha` | 0.1 - 0.3 | | +We aim to provide security fixes in the form of a new patch version for the +latest release version of `rand` and its dependencies `rand_core` and +`rand_chacha`, as well as for prior major and minor releases which were, at some +time during the previous 12 months, the latest release version. -Explanation of exceptions: - -- Jitter: `JitterRng` is used as an entropy source when the primary source - fails; this source may not be secure against side-channel attacks, see #699. -- ISAAC: the [ISAAC](https://burtleburtle.net/bob/rand/isaacafa.html) RNG used - to implement `ThreadRng` is difficult to analyse and thus cannot provide - strong assertions of security. - -## Known issues +## Reporting a Vulnerability -In `rand` version 0.3 (0.3.18 and later), if `OsRng` fails, `ThreadRng` is -seeded from the system time in an insecure manner. +If you have discovered a security vulnerability in this project, please report it privately. **Do not disclose it as a public issue.** This gives us time to work with you to fix the issue before public exposure, reducing the chance that the exploit will be used before a patch is released. -## Reporting a Vulnerability +Please disclose it at [security advisory](https://github.com/rust-random/rand/security/advisories/new). -To report a vulnerability, [open a new issue](https://github.com/rust-random/rand/issues/new). -Once the issue is resolved, the vulnerability should be [reported to RustSec](https://github.com/RustSec/advisory-db/blob/master/CONTRIBUTING.md). +This project is maintained by a team of volunteers on a reasonable-effort basis. As such, please give us at least 90 days to work on a fix before public exposure. From d3cae56734a321f0567fb05b66eb4f71a0014be6 Mon Sep 17 00:00:00 2001 From: Diggory Hardy Date: Wed, 5 Feb 2025 11:20:54 +0000 Subject: [PATCH 5/7] Update doc on traits CryptoRng, TryCryptoRng --- rand_core/src/lib.rs | 53 ++++++++++++++++++++++++++------------------ 1 file changed, 32 insertions(+), 21 deletions(-) diff --git a/rand_core/src/lib.rs b/rand_core/src/lib.rs index 9faff9c752f..86e0e51660f 100644 --- a/rand_core/src/lib.rs +++ b/rand_core/src/lib.rs @@ -175,12 +175,26 @@ where } } -/// A marker trait used to indicate that an [`RngCore`] implementation is -/// supposed to be cryptographically secure. +/// A marker trait over [`RngCore`] for securely unpredictable RNGs /// -/// *Cryptographically secure generators*, also known as *CSPRNGs*, should -/// satisfy an additional properties over other generators: given the first -/// *k* bits of an algorithm's output +/// This marker trait indicates that the implementing generator is intended, +/// when correctly seeded and protected from side-channel attacks such as a +/// leaking of state, to be a cryptographically secure generator. This trait is +/// provided as a tool to aid review of cryptographic code, but does not by +/// itself guarantee suitability for cryptographic applications. +/// +/// Implementors of `CryptoRng` automatically implement the [`TryCryptoRng`] +/// trait. +/// +/// Implementors of `CryptoRng` should only implement [`Default`] if the +/// `default()` instances are themselves secure generators: for example if the +/// implementing type is a stateless interface over a secure external generator +/// (like [`OsRng`]) or if the `default()` instance uses a strong, fresh seed. +/// +/// Formally, a CSPRNG (Cryptographically Secure Pseudo-Random Number Generator) +/// should satisfy an additional properties over other generators: assuming that +/// the generator has been appropriately seeded and has unknown state, then +/// given the first *k* bits of an algorithm's output /// sequence, it should not be possible using polynomial-time algorithms to /// predict the next bit with probability significantly greater than 50%. /// @@ -188,19 +202,6 @@ where /// required by this trait: if the CSPRNG's state is revealed, it should not be /// computationally-feasible to reconstruct output prior to this. Some other /// generators allow backwards-computation and are considered *reversible*. -/// -/// Note that this trait is provided for guidance only and cannot guarantee -/// suitability for cryptographic applications. In general it should only be -/// implemented for well-reviewed code implementing well-regarded algorithms. -/// -/// Note also that use of a `CryptoRng` does not protect against other -/// weaknesses such as seeding from a weak entropy source or leaking state. -/// -/// Note that implementors of [`CryptoRng`] also automatically implement -/// the [`TryCryptoRng`] trait. -/// -/// [`BlockRngCore`]: block::BlockRngCore -/// [`Infallible`]: core::convert::Infallible pub trait CryptoRng: RngCore {} impl CryptoRng for T where T::Target: CryptoRng {} @@ -269,10 +270,20 @@ impl TryRngCore for R { } } -/// A marker trait used to indicate that a [`TryRngCore`] implementation is -/// supposed to be cryptographically secure. +/// A marker trait over [`TryRngCore`] for securely unpredictable RNGs +/// +/// This trait is like [`CryptoRng`] but for the trait [`TryRngCore`]. +/// +/// This marker trait indicates that the implementing generator is intended, +/// when correctly seeded and protected from side-channel attacks such as a +/// leaking of state, to be a cryptographically secure generator. This trait is +/// provided as a tool to aid review of cryptographic code, but does not by +/// itself guarantee suitability for cryptographic applications. /// -/// See [`CryptoRng`] docs for more information about cryptographically secure generators. +/// Implementors of `TryCryptoRng` should only implement [`Default`] if the +/// `default()` instances are themselves secure generators: for example if the +/// implementing type is a stateless interface over a secure external generator +/// (like [`OsRng`]) or if the `default()` instance uses a strong, fresh seed. pub trait TryCryptoRng: TryRngCore {} impl TryCryptoRng for R {} From 2ad83ab822b74426a237cb5f539786f6a28c44ff Mon Sep 17 00:00:00 2001 From: Diggory Hardy Date: Wed, 5 Feb 2025 11:40:13 +0000 Subject: [PATCH 6/7] Updated SECURITY.md --- SECURITY.md | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/SECURITY.md b/SECURITY.md index c04f43ce451..f1a61b0d208 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -13,12 +13,21 @@ Rand provides the marker traits `CryptoRng`, `TryCryptoRng` and `CryptoBlockRng`. Generators (RNGs) implementing one of these traits which are used according to these additional constraints: -- If the RNG implements `Default`, it may be default-constructed -- If the RNG implements `SeedableRng`, it may be constructed and seeded using - `SeedableRng::from_seed` with a cryptographically secure seed value -- If the RNG implements `SeedableRng`, it may be constructed and seeded from - another RNG which is itself cryptographically secure -- The state (memory) of the RNG and its seed value are not exposed +- The generator may be constructed using `std::default::Default` where the + generator supports this trait. Note that generators should *only* support + `Default` where the `default()` instance is appropriately seeded: for + example `OsRng` has no state and thus has a trivial `default()` instance + while `ThreadRng::default()` returns a handle to a thread-local instance + seeded using `OsRng`. +- The generator may be constructed using `rand_core::SeedableRng` in any of + the following ways where the generator supports this trait: + + - Via `SeedableRng::from_seed` using a cryptographically secure seed value + - Via `SeedableRng::from_rng` or `try_from_rng` using a cryptographically + secure source `rng` + - Via `SeedableRng::from_os_rng` or `try_from_os_rng` +- The state (memory) of the generator and its seed value (or source `rng`) are + not exposed are expected to provide the following: From a7612c774b7cf31e315f95f1161da5d8b7354dcc Mon Sep 17 00:00:00 2001 From: Diggory Hardy Date: Wed, 5 Feb 2025 11:40:13 +0000 Subject: [PATCH 7/7] Updated SECURITY.md --- rand_core/src/lib.rs | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/rand_core/src/lib.rs b/rand_core/src/lib.rs index 86e0e51660f..11bdf656c75 100644 --- a/rand_core/src/lib.rs +++ b/rand_core/src/lib.rs @@ -192,16 +192,15 @@ where /// (like [`OsRng`]) or if the `default()` instance uses a strong, fresh seed. /// /// Formally, a CSPRNG (Cryptographically Secure Pseudo-Random Number Generator) -/// should satisfy an additional properties over other generators: assuming that +/// should satisfy an additional property over other generators: assuming that /// the generator has been appropriately seeded and has unknown state, then /// given the first *k* bits of an algorithm's output /// sequence, it should not be possible using polynomial-time algorithms to /// predict the next bit with probability significantly greater than 50%. /// -/// Some generators may satisfy an additional property, however this is not -/// required by this trait: if the CSPRNG's state is revealed, it should not be -/// computationally-feasible to reconstruct output prior to this. Some other -/// generators allow backwards-computation and are considered *reversible*. +/// An optional property of CSPRNGs is backtracking resistance: if the CSPRNG's +/// state is revealed, it will not be computationally-feasible to reconstruct +/// prior output values. This property is not required by `CryptoRng`. pub trait CryptoRng: RngCore {} impl CryptoRng for T where T::Target: CryptoRng {}