From b7384b7e6f0a581229e6e3a0379d2b6d12c54b25 Mon Sep 17 00:00:00 2001 From: David Sherret Date: Sat, 17 May 2025 15:03:50 -0400 Subject: [PATCH 1/5] Add runtime_error backend --- .github/workflows/build.yml | 14 ++++++++++++++ Cargo.toml | 2 +- README.md | 1 + src/backends.rs | 3 +++ src/backends/runtime_error.rs | 9 +++++++++ 5 files changed, 28 insertions(+), 1 deletion(-) create mode 100644 src/backends/runtime_error.rs diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 79dba1d04..2b298552f 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -273,3 +273,17 @@ jobs: - env: RUSTFLAGS: -Dwarnings --cfg getrandom_backend="custom" run: cargo build --target riscv32i-unknown-none-elf + + + runtime-error: + name: Runtime error + runs-on: ubuntu-24.04 + steps: + - uses: actions/checkout@v4 + - uses: dtolnay/rust-toolchain@stable + with: + targets: wasm32-unknown-unknown + - uses: Swatinem/rust-cache@v2 + - env: + RUSTFLAGS: -Dwarnings --cfg getrandom_backend="runtime_error" + run: cargo build --target wasm32-unknown-unknown diff --git a/Cargo.toml b/Cargo.toml index 371bc817b..27ccf4c4f 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -83,7 +83,7 @@ wasm-bindgen-test = "0.3" [lints.rust.unexpected_cfgs] level = "warn" check-cfg = [ - 'cfg(getrandom_backend, values("custom", "efi_rng", "rdrand", "rndr", "linux_getrandom", "linux_raw", "wasm_js"))', + 'cfg(getrandom_backend, values("custom", "efi_rng", "rdrand", "rndr", "linux_getrandom", "linux_raw", "wasm_js", "runtime_error"))', 'cfg(getrandom_msan)', 'cfg(getrandom_windows_legacy)', 'cfg(getrandom_test_linux_fallback)', diff --git a/README.md b/README.md index b0e17d477..a282adc42 100644 --- a/README.md +++ b/README.md @@ -87,6 +87,7 @@ of randomness based on their specific needs: | `wasm_js` | Web Browser, Node.js | `wasm32‑unknown‑unknown`, `wasm32v1-none` | [`Crypto.getRandomValues`]. Requires feature `wasm_js` ([see below](#webassembly-support)). | `efi_rng` | UEFI | `*-unknown‑uefi` | [`EFI_RNG_PROTOCOL`] with `EFI_RNG_ALGORITHM_RAW` (requires `std` and Nigthly compiler) | `custom` | All targets | `*` | User-provided custom implementation (see [custom backend]) +| `runtime_error` | All targets | `*` | Errors when providing randomness. Useful when only needing this crate to compile in wasm32, but it's not actually used. Opt-in backends can be enabled using the `getrandom_backend` configuration flag. The flag can be set either by specifying the `rustflags` field in [`.cargo/config.toml`]: diff --git a/src/backends.rs b/src/backends.rs index 2c539df26..a7a622d76 100644 --- a/src/backends.rs +++ b/src/backends.rs @@ -38,6 +38,9 @@ cfg_if! { )); } } + } else if #[cfg(getrandom_backend = "runtime_error")] { + mod runtime_error; + pub use runtime_error::*; } else if #[cfg(all(target_os = "linux", target_env = ""))] { mod linux_raw; pub use linux_raw::*; diff --git a/src/backends/runtime_error.rs b/src/backends/runtime_error.rs new file mode 100644 index 000000000..4ea381fc4 --- /dev/null +++ b/src/backends/runtime_error.rs @@ -0,0 +1,9 @@ +//! Implementation that errors at runtime. +use crate::Error; +use core::mem::MaybeUninit; + +pub use crate::util::{inner_u32, inner_u64}; + +pub fn fill_inner(_dest: &mut [MaybeUninit]) -> Result<(), Error> { + Err(Error::UNSUPPORTED) +} From fb606a61603b00b37711c150873800a508d80f5d Mon Sep 17 00:00:00 2001 From: David Sherret Date: Mon, 19 May 2025 00:28:11 -0400 Subject: [PATCH 2/5] review feedback --- .github/workflows/build.yml | 5 ++-- Cargo.toml | 2 +- README.md | 23 ++++++++----------- src/backends.rs | 6 ++--- .../{runtime_error.rs => unsupported.rs} | 0 5 files changed, 15 insertions(+), 21 deletions(-) rename src/backends/{runtime_error.rs => unsupported.rs} (100%) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 2b298552f..53144945e 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -274,8 +274,7 @@ jobs: RUSTFLAGS: -Dwarnings --cfg getrandom_backend="custom" run: cargo build --target riscv32i-unknown-none-elf - - runtime-error: + unsupported: name: Runtime error runs-on: ubuntu-24.04 steps: @@ -285,5 +284,5 @@ jobs: targets: wasm32-unknown-unknown - uses: Swatinem/rust-cache@v2 - env: - RUSTFLAGS: -Dwarnings --cfg getrandom_backend="runtime_error" + RUSTFLAGS: -Dwarnings --cfg getrandom_backend="unsupported" run: cargo build --target wasm32-unknown-unknown diff --git a/Cargo.toml b/Cargo.toml index 27ccf4c4f..4a982ee7c 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -83,7 +83,7 @@ wasm-bindgen-test = "0.3" [lints.rust.unexpected_cfgs] level = "warn" check-cfg = [ - 'cfg(getrandom_backend, values("custom", "efi_rng", "rdrand", "rndr", "linux_getrandom", "linux_raw", "wasm_js", "runtime_error"))', + 'cfg(getrandom_backend, values("custom", "efi_rng", "rdrand", "rndr", "linux_getrandom", "linux_raw", "wasm_js", "unsupported"))', 'cfg(getrandom_msan)', 'cfg(getrandom_windows_legacy)', 'cfg(getrandom_test_linux_fallback)', diff --git a/README.md b/README.md index a282adc42..46a0c38cc 100644 --- a/README.md +++ b/README.md @@ -87,7 +87,7 @@ of randomness based on their specific needs: | `wasm_js` | Web Browser, Node.js | `wasm32‑unknown‑unknown`, `wasm32v1-none` | [`Crypto.getRandomValues`]. Requires feature `wasm_js` ([see below](#webassembly-support)). | `efi_rng` | UEFI | `*-unknown‑uefi` | [`EFI_RNG_PROTOCOL`] with `EFI_RNG_ALGORITHM_RAW` (requires `std` and Nigthly compiler) | `custom` | All targets | `*` | User-provided custom implementation (see [custom backend]) -| `runtime_error` | All targets | `*` | Errors when providing randomness. Useful when only needing this crate to compile in wasm32, but it's not actually used. +| `unsupported` | All targets | `*` | Always returns `Err(Error::UNSUPPORTED)` (see [unsupported backend]) Opt-in backends can be enabled using the `getrandom_backend` configuration flag. The flag can be set either by specifying the `rustflags` field in [`.cargo/config.toml`]: @@ -204,20 +204,14 @@ unsafe extern "Rust" fn __getrandom_v03_custom( } ``` -If you are confident that `getrandom` is not used in your project, but -it gets pulled nevertheless by one of your dependencies, then you can -use the following custom backend, which always returns the "unsupported" error: -```rust -use getrandom::Error; +### Unsupported backend -#[no_mangle] -unsafe extern "Rust" fn __getrandom_v03_custom( - dest: *mut u8, - len: usize, -) -> Result<(), Error> { - Err(Error::UNSUPPORTED) -} -``` +In some rare scenarios you might be compiling this crate in a constrained +environment (ex. `wasm32-unknown-unknown`), but this crate's functionality +is not actually used by your code. If you are confident that `getrandom` is +not used in your project, but it gets pulled nevertheless by one of your +dependencies, then you can enable the `unsupported` backend, which always +returns `Err(Error::UNSUPPORTED)`. ### Platform Support @@ -374,6 +368,7 @@ dual licensed as above, without any additional terms or conditions. [`get-random-u64`]: https://github.com/WebAssembly/WASI/blob/v0.2.1/wasip2/random/random.wit#L23-L28 [configuration flags]: #configuration-flags [custom backend]: #custom-backend +[unsupported backend]: #unsupported-backend [`wasm-bindgen`]: https://github.com/rustwasm/wasm-bindgen [`module`]: https://rustwasm.github.io/wasm-bindgen/reference/attributes/on-js-imports/module.html [`sys_read_entropy`]: https://github.com/hermit-os/kernel/blob/315f58ff5efc81d9bf0618af85a59963ff55f8b1/src/syscalls/entropy.rs#L47-L55 diff --git a/src/backends.rs b/src/backends.rs index a7a622d76..dbe934565 100644 --- a/src/backends.rs +++ b/src/backends.rs @@ -38,9 +38,9 @@ cfg_if! { )); } } - } else if #[cfg(getrandom_backend = "runtime_error")] { - mod runtime_error; - pub use runtime_error::*; + } else if #[cfg(getrandom_backend = "unsupported")] { + mod unsupported; + pub use unsupported::*; } else if #[cfg(all(target_os = "linux", target_env = ""))] { mod linux_raw; pub use linux_raw::*; diff --git a/src/backends/runtime_error.rs b/src/backends/unsupported.rs similarity index 100% rename from src/backends/runtime_error.rs rename to src/backends/unsupported.rs From 05d56ba6e67eddf17da9c1c8cdf5811fd9b2706f Mon Sep 17 00:00:00 2001 From: David Sherret Date: Mon, 19 May 2025 00:49:48 -0400 Subject: [PATCH 3/5] update changelog and ex --- CHANGELOG.md | 9 +++++++++ README.md | 2 +- 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fbfe1d6db..26d4e3a03 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,15 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [0.3.4] - UNRELEASED + +### Added +- `unsupported` opt-in backend [#667] + +[#667]: https://github.com/rust-random/getrandom/pull/667 + +[0.3.4]: https://github.com/rust-random/getrandom/compare/v0.3.3...HEAD + ## [0.3.3] - 2025-05-09 ### Changed diff --git a/README.md b/README.md index 46a0c38cc..5e6a73d98 100644 --- a/README.md +++ b/README.md @@ -207,7 +207,7 @@ unsafe extern "Rust" fn __getrandom_v03_custom( ### Unsupported backend In some rare scenarios you might be compiling this crate in a constrained -environment (ex. `wasm32-unknown-unknown`), but this crate's functionality +environment (e.g. `wasm32-unknown-unknown`), but this crate's functionality is not actually used by your code. If you are confident that `getrandom` is not used in your project, but it gets pulled nevertheless by one of your dependencies, then you can enable the `unsupported` backend, which always From 40f3dcaabe90f6e98f5fcccc3e0d562e275a6954 Mon Sep 17 00:00:00 2001 From: David Sherret Date: Mon, 19 May 2025 00:50:40 -0400 Subject: [PATCH 4/5] diff link at end of file --- CHANGELOG.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 26d4e3a03..f51c2b59b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,8 +11,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 [#667]: https://github.com/rust-random/getrandom/pull/667 -[0.3.4]: https://github.com/rust-random/getrandom/compare/v0.3.3...HEAD - ## [0.3.3] - 2025-05-09 ### Changed @@ -596,6 +594,7 @@ Publish initial implementation. ## [0.0.0] - 2019-01-19 Publish an empty template library. +[0.3.4]: https://github.com/rust-random/getrandom/compare/v0.3.3...HEAD [0.3.3]: https://github.com/rust-random/getrandom/compare/v0.3.2...v0.3.3 [0.3.2]: https://github.com/rust-random/getrandom/compare/v0.3.1...v0.3.2 [0.3.1]: https://github.com/rust-random/getrandom/compare/v0.3.0...v0.3.1 From 0244492a91c708d90c907b004b64e02384225549 Mon Sep 17 00:00:00 2001 From: David Sherret Date: Mon, 19 May 2025 10:59:20 -0400 Subject: [PATCH 5/5] Update readme with suggestion --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 5e6a73d98..293eb88a1 100644 --- a/README.md +++ b/README.md @@ -206,8 +206,8 @@ unsafe extern "Rust" fn __getrandom_v03_custom( ### Unsupported backend -In some rare scenarios you might be compiling this crate in a constrained -environment (e.g. `wasm32-unknown-unknown`), but this crate's functionality +In some rare scenarios, you might be compiling this crate for an unsupported +target (e.g. `wasm32-unknown-unknown`), but this crate's functionality is not actually used by your code. If you are confident that `getrandom` is not used in your project, but it gets pulled nevertheless by one of your dependencies, then you can enable the `unsupported` backend, which always