| 1 | // Copyright 2018 Developers of the Rand project. |
| 2 | // |
|---|
| 3 | // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or |
|---|
| 4 | // https://www.apache.org/licenses/LICENSE-2.0> or the MIT license |
|---|
| 5 | // <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your |
|---|
| 6 | // option. This file may not be copied, modified, or distributed |
|---|
| 7 | // except according to those terms. |
|---|
| 8 | |
|---|
| 9 | //! The ChaCha random number generators. |
|---|
| 10 | //! |
|---|
| 11 | //! These are native Rust implementations of RNGs derived from the |
|---|
| 12 | //! [ChaCha stream ciphers] by D J Bernstein. |
|---|
| 13 | //! |
|---|
| 14 | //! ## Generators |
|---|
| 15 | //! |
|---|
| 16 | //! This crate provides 8-, 12- and 20-round variants of generators via a "core" |
|---|
| 17 | //! implementation (of [`BlockRngCore`]), each with an associated "RNG" type |
|---|
| 18 | //! (implementing [`RngCore`]). |
|---|
| 19 | //! |
|---|
| 20 | //! These generators are all deterministic and portable (see [Reproducibility] |
|---|
| 21 | //! in the book), with testing against reference vectors. |
|---|
| 22 | //! |
|---|
| 23 | //! ## Cryptographic (secure) usage |
|---|
| 24 | //! |
|---|
| 25 | //! Where secure unpredictable generators are required, it is suggested to use |
|---|
| 26 | //! [`ChaCha12Rng`] or [`ChaCha20Rng`] and to seed via |
|---|
| 27 | //! [`SeedableRng::from_os_rng`]. |
|---|
| 28 | //! |
|---|
| 29 | //! See also the [Security] chapter in the rand book. The crate is provided |
|---|
| 30 | //! "as is", without any form of guarantee, and without a security audit. |
|---|
| 31 | //! |
|---|
| 32 | //! ## Seeding (construction) |
|---|
| 33 | //! |
|---|
| 34 | //! Generators implement the [`SeedableRng`] trait. Any method may be used, |
|---|
| 35 | //! but note that `seed_from_u64` is not suitable for usage where security is |
|---|
| 36 | //! important. Some suggestions: |
|---|
| 37 | //! |
|---|
| 38 | //! 1. With a fresh seed, **direct from the OS** (implies a syscall): |
|---|
| 39 | //! ``` |
|---|
| 40 | //! # use {rand_core::SeedableRng, rand_chacha::ChaCha12Rng}; |
|---|
| 41 | //! let rng = ChaCha12Rng::from_os_rng(); |
|---|
| 42 | //! # let _: ChaCha12Rng = rng; |
|---|
| 43 | //! ``` |
|---|
| 44 | //! 2. **From a master generator.** This could be [`rand::rng`] |
|---|
| 45 | //! (effectively a fresh seed without the need for a syscall on each usage) |
|---|
| 46 | //! or a deterministic generator such as [`ChaCha20Rng`]. |
|---|
| 47 | //! Beware that should a weak master generator be used, correlations may be |
|---|
| 48 | //! detectable between the outputs of its child generators. |
|---|
| 49 | //! ```ignore |
|---|
| 50 | //! let rng = ChaCha12Rng::from_rng(&mut rand::rng()); |
|---|
| 51 | //! ``` |
|---|
| 52 | //! |
|---|
| 53 | //! See also [Seeding RNGs] in the book. |
|---|
| 54 | //! |
|---|
| 55 | //! ## Generation |
|---|
| 56 | //! |
|---|
| 57 | //! Generators implement [`RngCore`], whose methods may be used directly to |
|---|
| 58 | //! generate unbounded integer or byte values. |
|---|
| 59 | //! ``` |
|---|
| 60 | //! use rand_core::{SeedableRng, RngCore}; |
|---|
| 61 | //! use rand_chacha::ChaCha12Rng; |
|---|
| 62 | //! |
|---|
| 63 | //! let mut rng = ChaCha12Rng::from_seed(Default::default()); |
|---|
| 64 | //! let x = rng.next_u64(); |
|---|
| 65 | //! assert_eq!(x, 0x53f955076a9af49b); |
|---|
| 66 | //! ``` |
|---|
| 67 | //! |
|---|
| 68 | //! It is often more convenient to use the [`rand::Rng`] trait, which provides |
|---|
| 69 | //! further functionality. See also the [Random Values] chapter in the book. |
|---|
| 70 | //! |
|---|
| 71 | //! [ChaCha stream ciphers]: https://cr.yp.to/chacha.html |
|---|
| 72 | //! [Reproducibility]: https://rust-random.github.io/book/crate-reprod.html |
|---|
| 73 | //! [Seeding RNGs]: https://rust-random.github.io/book/guide-seeding.html |
|---|
| 74 | //! [Security]: https://rust-random.github.io/book/guide-rngs.html#security |
|---|
| 75 | //! [Random Values]: https://rust-random.github.io/book/guide-values.html |
|---|
| 76 | //! [`BlockRngCore`]: rand_core::block::BlockRngCore |
|---|
| 77 | //! [`RngCore`]: rand_core::RngCore |
|---|
| 78 | //! [`SeedableRng`]: rand_core::SeedableRng |
|---|
| 79 | //! [`SeedableRng::from_os_rng`]: rand_core::SeedableRng::from_os_rng |
|---|
| 80 | //! [`rand::rng`]: https://docs.rs/rand/latest/rand/fn.rng.html |
|---|
| 81 | //! [`rand::Rng`]: https://docs.rs/rand/latest/rand/trait.Rng.html |
|---|
| 82 | |
|---|
| 83 | #![doc ( |
|---|
| 84 | html_logo_url = "https://www.rust-lang.org/logos/rust-logo-128x128-blk.png" , |
|---|
| 85 | html_favicon_url = "https://www.rust-lang.org/favicon.ico" , |
|---|
| 86 | html_root_url = "https://rust-random.github.io/rand/" |
|---|
| 87 | )] |
|---|
| 88 | #![forbid (unsafe_code)] |
|---|
| 89 | #![deny (missing_docs)] |
|---|
| 90 | #![deny (missing_debug_implementations)] |
|---|
| 91 | #![doc (test(attr(allow(unused_variables), deny(warnings))))] |
|---|
| 92 | #![cfg_attr (not(feature = "std" ), no_std)] |
|---|
| 93 | |
|---|
| 94 | pub use rand_core; |
|---|
| 95 | |
|---|
| 96 | mod chacha; |
|---|
| 97 | mod guts; |
|---|
| 98 | |
|---|
| 99 | pub use crate::chacha::{ |
|---|
| 100 | ChaCha12Core, ChaCha12Rng, ChaCha20Core, ChaCha20Rng, ChaCha8Core, ChaCha8Rng, |
|---|
| 101 | }; |
|---|
| 102 | |
|---|
| 103 | /// ChaCha with 20 rounds |
|---|
| 104 | pub type ChaChaRng = ChaCha20Rng; |
|---|
| 105 | /// ChaCha with 20 rounds, low-level interface |
|---|
| 106 | pub type ChaChaCore = ChaCha20Core; |
|---|
| 107 | |
|---|
