]>
Commit | Line | Data |
---|---|---|
f20569fa XL |
1 | # getrandom |
2 | ||
064997fb FG |
3 | [![Build Status]][GitHub Actions] [![Crate]][crates.io] [![Documentation]][docs.rs] [![Dependency Status]][deps.rs] [![Downloads]][crates.io] [![License]][LICENSE-MIT] |
4 | ||
5 | [GitHub Actions]: https://github.com/rust-random/getrandom/actions?query=workflow:Tests+branch:master | |
4b012472 | 6 | [Build Status]: https://github.com/rust-random/getrandom/actions/workflows/tests.yml/badge.svg?branch=master |
064997fb FG |
7 | [crates.io]: https://crates.io/crates/getrandom |
8 | [Crate]: https://img.shields.io/crates/v/getrandom | |
9 | [docs.rs]: https://docs.rs/getrandom | |
10 | [Documentation]: https://docs.rs/getrandom/badge.svg | |
11 | [deps.rs]: https://deps.rs/repo/github/rust-random/getrandom | |
12 | [Dependency Status]: https://deps.rs/repo/github/rust-random/getrandom/status.svg | |
13 | [Downloads]: https://img.shields.io/crates/d/getrandom | |
14 | [LICENSE-MIT]: https://raw.githubusercontent.com/rust-random/getrandom/master/LICENSE-MIT | |
15 | [License]: https://img.shields.io/crates/l/getrandom | |
f20569fa XL |
16 | |
17 | ||
49aad941 FG |
18 | A Rust library for retrieving random data from (operating) system sources. It is |
19 | assumed that the system always provides high-quality cryptographically secure random | |
f20569fa | 20 | data, ideally backed by hardware entropy sources. This crate derives its name |
49aad941 | 21 | from Linux's `getrandom` function, but is cross-platform, roughly supporting |
f20569fa XL |
22 | the same set of platforms as Rust's `std` lib. |
23 | ||
24 | This is a low-level API. Most users should prefer using high-level random-number | |
25 | library like [`rand`]. | |
26 | ||
27 | [`rand`]: https://crates.io/crates/rand | |
28 | ||
29 | ## Usage | |
30 | ||
31 | Add this to your `Cargo.toml`: | |
32 | ||
33 | ```toml | |
34 | [dependencies] | |
35 | getrandom = "0.2" | |
36 | ``` | |
37 | ||
38 | Then invoke the `getrandom` function: | |
39 | ||
40 | ```rust | |
41 | fn get_random_buf() -> Result<[u8; 32], getrandom::Error> { | |
42 | let mut buf = [0u8; 32]; | |
43 | getrandom::getrandom(&mut buf)?; | |
44 | Ok(buf) | |
45 | } | |
46 | ``` | |
47 | ||
48 | For more information about supported targets, entropy sources, `no_std` targets, | |
49 | crate features, WASM support and Custom RNGs see the | |
50 | [`getrandom` documentation](https://docs.rs/getrandom/latest) and | |
51 | [`getrandom::Error` documentation](https://docs.rs/getrandom/latest/getrandom/struct.Error.html). | |
52 | ||
53 | ## Minimum Supported Rust Version | |
54 | ||
49aad941 | 55 | This crate requires Rust 1.36.0 or later. |
f20569fa XL |
56 | |
57 | # License | |
58 | ||
59 | The `getrandom` library is distributed under either of | |
60 | ||
61 | * [Apache License, Version 2.0](LICENSE-APACHE) | |
62 | * [MIT license](LICENSE-MIT) | |
63 | ||
64 | at your option. |