diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 79dba1d04..53144945e 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -273,3 +273,16 @@ jobs: - env: RUSTFLAGS: -Dwarnings --cfg getrandom_backend="custom" run: cargo build --target riscv32i-unknown-none-elf + + unsupported: + 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="unsupported" + run: cargo build --target wasm32-unknown-unknown diff --git a/CHANGELOG.md b/CHANGELOG.md index fbfe1d6db..f51c2b59b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,13 @@ 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.3] - 2025-05-09 ### Changed @@ -587,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 diff --git a/Cargo.toml b/Cargo.toml index 371bc817b..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"))', + '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 b0e17d477..293eb88a1 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]) +| `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`]: @@ -203,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 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 +returns `Err(Error::UNSUPPORTED)`. ### Platform Support @@ -373,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 2c539df26..dbe934565 100644 --- a/src/backends.rs +++ b/src/backends.rs @@ -38,6 +38,9 @@ cfg_if! { )); } } + } 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/unsupported.rs b/src/backends/unsupported.rs new file mode 100644 index 000000000..4ea381fc4 --- /dev/null +++ b/src/backends/unsupported.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) +}