From 34c0e9efee2206e0fd4ff79992422778323f668b Mon Sep 17 00:00:00 2001 From: Joe Richey Date: Mon, 25 May 2020 03:03:21 -0700 Subject: [PATCH] Update docs for 0.2 The main things here are clarifying how fallback functionatliy works. Signed-off-by: Joe Richey --- Cargo.toml | 6 +-- README.md | 25 ++--------- src/custom.rs | 40 +++++++++++++++--- src/error.rs | 8 +++- src/lib.rs | 115 +++++++++++++++++++++++++++++--------------------- src/stdweb.rs | 3 +- 6 files changed, 119 insertions(+), 78 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 83df2da9..d4642fce 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -35,8 +35,9 @@ wasm-bindgen = { version = "0.2.62", default-features = false, optional = true } wasm-bindgen-test = "0.3.12" [features] +# Implement std-only traits for getrandom::Error std = [] -# Feature to enable fallback RDRAND-based implementation +# Feature to enable fallback RDRAND-based implementation on x86/x86_64 rdrand = [] # Feature to enable JavaScript bindings on wasm32-unknown-unknown js = ["stdweb", "wasm-bindgen"] @@ -44,8 +45,7 @@ js = ["stdweb", "wasm-bindgen"] custom = [] # Unstable feature to support being a libstd dependency rustc-dep-of-std = ["compiler_builtins", "core"] - -# Test/wasm-bindgen only feature to run tests in a browser +# Unstable/test-only feature to run wasm-bindgen tests in a browser test-in-browser = [] [package.metadata.docs.rs] diff --git a/README.md b/README.md index e5fdf9ab..c941596d 100644 --- a/README.md +++ b/README.md @@ -37,27 +37,10 @@ fn get_random_buf() -> Result<[u8; 32], getrandom::Error> { } ``` -## Features - -This library is `no_std` for every supported target. However, getting randomness -usually requires calling some external system API. This means most platforms -will require linking against system libraries (i.e. `libc` for Unix, -`Advapi32.dll` for Windows, Security framework on iOS, etc...). - -For the `wasm32-unknown-unknown` target, one of the following features should be -enabled: - -- [`wasm-bindgen`](https://crates.io/crates/wasm_bindgen) -- [`stdweb`](https://crates.io/crates/stdweb) - -By default, compiling `getrandom` for an unsupported target will result in -a compilation error. If you want to build an application which uses `getrandom` -for such target, you can either: -- Use [`[replace]`][replace] or [`[patch]`][patch] section in your `Cargo.toml` -to switch to a custom implementation with a support of your target. - -[replace]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-replace-section -[patch]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-patch-section +For more information about supported targets, entropy sources, `no_std` targets, +crate features, WASM support and Custom RNGs see the +[`getrandom` documentation](https://docs.rs/getrandom/latest) and +[`getrandom::Error` documentation](https://docs.rs/getrandom/latest/getrandom/struct.Error.html). ## Minimum Supported Rust Version diff --git a/src/custom.rs b/src/custom.rs index 71a1533c..18ac6c67 100644 --- a/src/custom.rs +++ b/src/custom.rs @@ -10,13 +10,43 @@ use crate::Error; use core::num::NonZeroU32; -/// Register a function to be invoked by `getrandom` on custom targets. +/// Register a function to be invoked by `getrandom` on unsupported targets. /// -/// This function will only be invoked on targets not supported by `getrandom`. -/// This prevents crate dependencies from either inadvertently or maliciously -/// overriding the secure RNG implementations in `getrandom`. +/// *This API requires the following Cargo features to be activated: `"custom"`* /// -/// *This API requires the following crate features to be activated: `custom`* +/// ## Writing your own custom `getrandom` implementation +/// +/// Users can define custom implementations either in their root crate or in a +/// target specific helper-crate. We will use the helper-crate approach in this +/// example, defining `dummy-getrandom`, an implementation that always fails. +/// +/// First, in `dummy-getrandom/Cargo.toml` we depend on `getrandom`: +/// ```toml +/// [dependencies] +/// getrandom = { version = "0.2", features = ["custom"] } +/// ``` +/// +/// Next, in `dummy-getrandom/src/lib.rs`, we define our custom implementation and register it: +/// ```rust +/// use core::num::NonZeroU32; +/// use getrandom::{Error, register_custom_getrandom}; +/// +/// const MY_CUSTOM_ERROR_CODE: u32 = Error::CUSTOM_START + 42; +/// fn always_fail(buf: &mut [u8]) -> Result<(), Error> { +/// let code = NonZeroU32::new(MY_CUSTOM_ERROR_CODE).unwrap(); +/// Err(Error::from(code)) +/// } +/// +/// register_custom_getrandom!(always_fail); +/// ``` +/// the registered function must have the same type signature as +/// [`getrandom::getrandom`](crate::getrandom). +/// +/// Now any user of `getrandom` (direct or indirect) on this target will use the +/// above custom implementation. Note that if you are using a helper-crate, some +/// crate in the build needs to depend on `dummy-getrandom` via a +/// `use dummy_getrandom;` statement. Failure to do this will result +/// in linker errors. #[macro_export] macro_rules! register_custom_getrandom { ($path:path) => { diff --git a/src/error.rs b/src/error.rs index 7b5d3ca4..48abdc11 100644 --- a/src/error.rs +++ b/src/error.rs @@ -7,7 +7,7 @@ // except according to those terms. use core::{fmt, num::NonZeroU32}; -/// A small and `no_std` compatible error type. +/// A small and `no_std` compatible error type /// /// The [`Error::raw_os_error()`] will indicate if the error is from the OS, and /// if so, which error code the OS gave the application. If such an error is @@ -15,6 +15,12 @@ use core::{fmt, num::NonZeroU32}; /// /// Internally this type is a NonZeroU32, with certain values reserved for /// certain purposes, see [`Error::INTERNAL_START`] and [`Error::CUSTOM_START`]. +/// +/// *If this crate's `"std"` Cargo feature is enabled*, then: +/// - [`getrandom::Error`][Error] implements +/// [`std::error::Error`](https://doc.rust-lang.org/std/error/trait.Error.html) +/// - [`std::io::Error`](https://doc.rust-lang.org/std/io/struct.Error.html) implements +/// [`From`](https://doc.rust-lang.org/std/convert/trait.From.html). #[derive(Copy, Clone, Eq, PartialEq)] pub struct Error(NonZeroU32); diff --git a/src/lib.rs b/src/lib.rs index 2cfc20d8..7d40766a 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -6,14 +6,15 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! Interface to the random number generator of the operating system. +//! Interface to the operating system's random number generator. //! -//! # Platform sources +//! # Supported targets //! -//! | OS | interface +//! | Target | Implementation //! |------------------|--------------------------------------------------------- //! | Linux, Android | [`getrandom`][1] system call if available, otherwise [`/dev/urandom`][2] after successfully polling `/dev/random` //! | Windows | [`RtlGenRandom`][3] +//! | [Windows UWP][22]| [`BCryptGenRandom`][23] //! | macOS | [`getentropy()`][19] if available, otherwise [`/dev/random`][20] (identical to `/dev/urandom`) //! | iOS | [`SecRandomCopyBytes`][4] //! | FreeBSD | [`getrandom()`][21] if available, otherwise [`kern.arandom`][5] @@ -27,65 +28,86 @@ //! | Haiku | `/dev/random` (identical to `/dev/urandom`) //! | SGX | [RDRAND][18] //! | VxWorks | `randABytes` after checking entropy pool initialization with `randSecure` -//! | Web browsers | [`Crypto.getRandomValues`][14] (see [Support for WebAssembly and asm.js][16]) -//! | Node.js | [`crypto.randomBytes`][15] (see [Support for WebAssembly and asm.js][16]) +//! | Emscripten | `/dev/random` (identical to `/dev/urandom`) //! | WASI | [`__wasi_random_get`][17] +//! | Web Browser | [`Crypto.getRandomValues()`][14], see [support for WebAssembly][16] +//! | Node.js | [`crypto.randomBytes`][15], see [support for WebAssembly][16] //! -//! Getrandom doesn't have a blanket implementation for all Unix-like operating -//! systems that reads from `/dev/urandom`. This ensures all supported operating -//! systems are using the recommended interface and respect maximum buffer -//! sizes. +//! There is no blanket implementation on `unix` targets that reads from +//! `/dev/urandom`. This ensures all supported targets are using the recommended +//! interface and respect maximum buffer sizes. +//! +//! Pull Requests that add support for new targets to `getrandom` are always welcome. //! //! ## Unsupported targets //! -//! By default, compiling `getrandom` for an unsupported target will result in -//! a compilation error. If you want to build an application which uses `getrandom` -//! for such target, you can either: -//! - Use [`[replace]`][replace] or [`[patch]`][patch] section in your `Cargo.toml` -//! to switch to a custom implementation with a support of your target. +//! By default, `getrandom` will not compile on unsupported targets, but certain +//! features allow a user to select a "fallback" implementation if no supported +//! implementation exists. +//! +//! All of the below mechanisms only affect unsupported +//! targets. Supported targets will _always_ use their supported implementations. +//! This prevents a crate from overriding a secure source of randomness +//! (either accidentally or intentionally). +//! +//! ### RDRAND on x86 //! -//! [replace]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-replace-section -//! [patch]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-patch-section +//! *If the `"rdrand"` Cargo feature is enabled*, `getrandom` will fallback to using +//! the [`RDRAND`][18] instruction to get randomness on `no_std` `x86`/`x86_64` +//! targets. This feature has no effect on other CPU architectures. //! -//! ## Support for WebAssembly and asm.js +//! ### Support for WebAssembly //! -//! Getrandom supports all of Rust's current `wasm32` targets, and it works with -//! both Node.js and web browsers. The three Emscripten targets -//! `asmjs-unknown-emscripten`, `wasm32-unknown-emscripten`, and -//! `wasm32-experimental-emscripten` use Emscripten's `/dev/random` emulation. -//! The WASI target `wasm32-wasi` uses the [`__wasi_random_get`][17] function -//! defined by the WASI standard. +//! This crate fully supports the `wasm32-wasi` and `wasm32-unknown-emscripten` +//! targets. However, the `wasm32-unknown-unknown` target is not supported since, +//! from the target name alone, we cannot deduce which JavaScript interface is +//! in use (or if JavaScript is available at all). //! -//! Getrandom also supports `wasm32-unknown-unknown` by directly calling -//! JavaScript methods. Rust currently has two ways to do this: [bindgen] and -//! [stdweb]. Getrandom supports using either one by enabling the -//! `wasm-bindgen` or `stdweb` crate features. Note that if both features are -//! enabled, `wasm-bindgen` will be used. If neither feature is enabled, calls -//! to `getrandom` will always fail at runtime. +//! Instead, *if the `"js"` Cargo feature is enabled*, this crate will assume +//! that you are building for an environment containing JavaScript, and will +//! call the appropriate methods. Both Browser and Node.js environments are +//! supported (see above), and both [wasm-bindgen] and [stdweb] toolchains are +//! supported. //! -//! [bindgen]: https://github.com/rust-lang/rust-bindgen +//! [wasm-bindgen]: https://github.com/rust-lang/rust-bindgen //! [stdweb]: https://github.com/koute/stdweb //! +//! ### Use a custom implementation +//! +//! Some external crates define `getrandom` implementations for specific +//! unsupported targets. If you depend on one of these external crates and you +//! are building for an unsupported target, `getrandom` will use this external +//! implementation instead of failing to compile. +//! +//! See [`register_custom_getrandom!`] for information about writing your own +//! custom `getrandom` implementation for an unsupported target. +//! +//! ### Indirect Dependencies +//! +//! If `getrandom` is not a direct dependency of your crate, you can still +//! enable any of above fallback behaviors by simply enabling the relevant +//! feature in your root crate's `[dependencies]` section: +//! ```toml +//! getrandom = { version = "0.2", features = ["rdrand"] } +//! ``` +//! //! ## Early boot //! -//! It is possible that early in the boot process the OS hasn't had enough time -//! yet to collect entropy to securely seed its RNG, especially on virtual -//! machines. +//! Sometimes, early in the boot process, the OS has not collected enough +//! entropy to securely seed its RNG. This is especially common on virtual +//! machines, where standard "random" events are hard to come by. //! -//! Some operating systems always block the thread until the RNG is securely +//! Some operating system interfaces always block until the RNG is securely //! seeded. This can take anywhere from a few seconds to more than a minute. -//! Others make a best effort to use a seed from before the shutdown and don't -//! document much. +//! A few (Linux, NetBSD and Solaris) offer a choice between blocking and +//! getting an error; in these cases, we always choose to block. //! -//! A few, Linux, NetBSD and Solaris, offer a choice between blocking and -//! getting an error; in these cases we always choose to block. -//! -//! On Linux (when the `getrandom` system call is not available) and on NetBSD -//! reading from `/dev/urandom` never blocks, even when the OS hasn't collected -//! enough entropy yet. To avoid returning low-entropy bytes, we first read from +//! On Linux (when the `getrandom` system call is not available), reading from +//! `/dev/urandom` never blocks, even when the OS hasn't collected enough +//! entropy yet. To avoid returning low-entropy bytes, we first poll //! `/dev/random` and only switch to `/dev/urandom` once this has succeeded. //! -//! # Error handling +//! ## Error handling //! //! We always choose failure over returning insecure "random" bytes. In general, //! on supported platforms, failure is highly unlikely, though not impossible. @@ -93,9 +115,6 @@ //! `getrandom`, hence after the first successful call one can be reasonably //! confident that no errors will occur. //! -//! On unsupported platforms, `getrandom` always fails. See the [`Error`] type -//! for more information on what data is returned on failure. -//! //! [1]: http://man7.org/linux/man-pages/man2/getrandom.2.html //! [2]: http://man7.org/linux/man-pages/man4/urandom.4.html //! [3]: https://docs.microsoft.com/en-us/windows/desktop/api/ntsecapi/nf-ntsecapi-rtlgenrandom @@ -111,12 +130,14 @@ //! [13]: https://github.com/nuxinl/cloudabi#random_get //! [14]: https://www.w3.org/TR/WebCryptoAPI/#Crypto-method-getRandomValues //! [15]: https://nodejs.org/api/crypto.html#crypto_crypto_randombytes_size_callback -//! [16]: #support-for-webassembly-and-asmjs +//! [16]: #support-for-webassembly //! [17]: https://github.com/WebAssembly/WASI/blob/master/design/WASI-core.md#__wasi_random_get //! [18]: https://software.intel.com/en-us/articles/intel-digital-random-number-generator-drng-software-implementation-guide //! [19]: https://www.unix.com/man-page/mojave/2/getentropy/ //! [20]: https://www.unix.com/man-page/mojave/4/random/ //! [21]: https://www.freebsd.org/cgi/man.cgi?query=getrandom&manpath=FreeBSD+12.0-stable +//! [22]: https://docs.microsoft.com/en-us/windows/uwp/ +//! [23]: https://docs.microsoft.com/en-us/windows/win32/api/bcrypt/nf-bcrypt-bcryptgenrandom #![doc( html_logo_url = "https://www.rust-lang.org/logos/rust-logo-128x128-blk.png", diff --git a/src/stdweb.rs b/src/stdweb.rs index 5a50b68d..83ae2b65 100644 --- a/src/stdweb.rs +++ b/src/stdweb.rs @@ -10,7 +10,8 @@ use crate::Error; extern crate std; use std::thread_local; -use stdweb::js; +#[macro_use] +extern crate stdweb; #[derive(Clone, Copy, PartialEq)] enum RngSource {