| 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; |