diff options
Diffstat (limited to 'src/lib.rs')
| -rw-r--r-- | src/lib.rs | 76 |
1 files changed, 55 insertions, 21 deletions
@@ -30,9 +30,9 @@ //! | ESP-IDF | `*‑espidf` | [`esp_fill_random`] //! | Emscripten | `*‑emscripten` | `/dev/random` (identical to `/dev/urandom`) //! | WASI | `wasm32‑wasi` | [`random_get`] -//! | Web Browser | `wasm32‑*‑unknown` | [`Crypto.getRandomValues`], see [WebAssembly support] -//! | Node.js | `wasm32‑*‑unknown` | [`crypto.randomBytes`], see [WebAssembly support] +//! | Web Browser and Node.js | `wasm32‑*‑unknown` | [`Crypto.getRandomValues`] if available, then [`crypto.randomFillSync`] if on Node.js, see [WebAssembly support] //! | SOLID | `*-kmc-solid_*` | `SOLID_RNG_SampleRandomBytes` +//! | Nintendo 3DS | `armv6k-nintendo-3ds` | [`getrandom`][1] //! //! There is no blanket implementation on `unix` targets that reads from //! `/dev/urandom`. This ensures all supported targets are using the recommended @@ -71,11 +71,37 @@ //! that you are building for an environment containing JavaScript, and will //! call the appropriate methods. Both web browser (main window and Web Workers) //! and Node.js environments are supported, invoking the methods -//! [described above](#supported-targets) using the -//! [wasm-bindgen](https://github.com/rust-lang/rust-bindgen) toolchain. +//! [described above](#supported-targets) using the [`wasm-bindgen`] toolchain. +//! +//! To enable the `js` Cargo feature, add the following to the `dependencies` +//! section in your `Cargo.toml` file: +//! ```toml +//! [dependencies] +//! getrandom = { version = "0.2", features = ["js"] } +//! ``` +//! +//! This can be done even if `getrandom` is not a direct dependency. Cargo +//! allows crates to enable features for indirect dependencies. +//! +//! This feature should only be enabled for binary, test, or benchmark crates. +//! Library crates should generally not enable this feature, leaving such a +//! decision to *users* of their library. Also, libraries should not introduce +//! their own `js` features *just* to enable `getrandom`'s `js` feature. //! //! This feature has no effect on targets other than `wasm32-unknown-unknown`. //! +//! #### Node.js ES module support +//! +//! Node.js supports both [CommonJS modules] and [ES modules]. Due to +//! limitations in wasm-bindgen's [`module`] support, we cannot directly +//! support ES Modules running on Node.js. However, on Node v15 and later, the +//! module author can add a simple shim to support the Web Cryptography API: +//! ```js +//! import { webcrypto } from 'node:crypto' +//! globalThis.crypto = webcrypto +//! ``` +//! This crate will then use the provided `webcrypto` implementation. +//! //! ### Custom implementations //! //! The [`register_custom_getrandom!`] macro allows a user to mark their own @@ -88,16 +114,6 @@ //! using `rdrand` and `js` Cargo features) continue using their normal //! implementations even if a function is registered. //! -//! ### Indirect Dependencies -//! -//! If `getrandom` is not a direct dependency of your crate, you can still -//! enable any of the above fallback behaviors by enabling the relevant -//! feature in your root crate's `Cargo.toml`: -//! ```toml -//! [dependencies] -//! getrandom = { version = "0.2", features = ["js"] } -//! ``` -//! //! ## Early boot //! //! Sometimes, early in the boot process, the OS has not collected enough @@ -114,13 +130,22 @@ //! entropy yet. To avoid returning low-entropy bytes, we first poll //! `/dev/random` and only switch to `/dev/urandom` once this has succeeded. //! +//! On OpenBSD, this kind of entropy accounting isn't available, and on +//! NetBSD, blocking on it is discouraged. On these platforms, nonblocking +//! interfaces are used, even when reliable entropy may not be available. +//! On the platforms where it is used, the reliability of entropy accounting +//! itself isn't free from controversy. This library provides randomness +//! sourced according to the platform's best practices, but each platform has +//! its own limits on the grade of randomness it can promise in environments +//! with few sources of entropy. +//! //! ## Error handling //! -//! We always choose failure over returning insecure "random" bytes. In general, -//! on supported platforms, failure is highly unlikely, though not impossible. -//! If an error does occur, then it is likely that it will occur on every call to -//! `getrandom`, hence after the first successful call one can be reasonably -//! confident that no errors will occur. +//! We always choose failure over returning known insecure "random" bytes. In +//! general, on supported platforms, failure is highly unlikely, though not +//! impossible. If an error does occur, then it is likely that it will occur +//! on every call to `getrandom`, hence after the first successful call one +//! can be reasonably confident that no errors will occur. //! //! [1]: http://man7.org/linux/man-pages/man2/getrandom.2.html //! [2]: http://man7.org/linux/man-pages/man4/urandom.4.html @@ -140,15 +165,19 @@ //! [`RDRAND`]: https://software.intel.com/en-us/articles/intel-digital-random-number-generator-drng-software-implementation-guide //! [`SecRandomCopyBytes`]: https://developer.apple.com/documentation/security/1399291-secrandomcopybytes?language=objc //! [`cprng_draw`]: https://fuchsia.dev/fuchsia-src/zircon/syscalls/cprng_draw -//! [`crypto.randomBytes`]: https://nodejs.org/api/crypto.html#crypto_crypto_randombytes_size_callback +//! [`crypto.randomFillSync`]: https://nodejs.org/api/crypto.html#cryptorandomfillsyncbuffer-offset-size //! [`esp_fill_random`]: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/random.html#_CPPv415esp_fill_randomPv6size_t //! [`random_get`]: https://github.com/WebAssembly/WASI/blob/main/phases/snapshot/docs.md#-random_getbuf-pointeru8-buf_len-size---errno //! [WebAssembly support]: #webassembly-support +//! [`wasm-bindgen`]: https://github.com/rustwasm/wasm-bindgen +//! [`module`]: https://rustwasm.github.io/wasm-bindgen/reference/attributes/on-js-imports/module.html +//! [CommonJS modules]: https://nodejs.org/api/modules.html +//! [ES modules]: https://nodejs.org/api/esm.html #![doc( html_logo_url = "https://www.rust-lang.org/logos/rust-logo-128x128-blk.png", html_favicon_url = "https://www.rust-lang.org/favicon.ico", - html_root_url = "https://docs.rs/getrandom/0.2.5" + html_root_url = "https://docs.rs/getrandom/0.2.8" )] #![no_std] #![warn(rust_2018_idioms, unused_lifetimes, missing_docs)] @@ -223,6 +252,11 @@ cfg_if! { } else if #[cfg(all(feature = "js", target_arch = "wasm32", target_os = "unknown"))] { #[path = "js.rs"] mod imp; + } else if #[cfg(all(target_os = "horizon", target_arch = "arm"))] { + // We check for target_arch = "arm" because the Nintendo Switch also + // uses Horizon OS (it is aarch64). + mod util_libc; + #[path = "3ds.rs"] mod imp; } else if #[cfg(feature = "custom")] { use custom as imp; } else if #[cfg(all(target_arch = "wasm32", target_os = "unknown"))] { |