rand_chacha/
lib.rs

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
94pub use rand_core;
95
96mod chacha;
97mod guts;
98
99pub use crate::chacha::{
100    ChaCha12Core, ChaCha12Rng, ChaCha20Core, ChaCha20Rng, ChaCha8Core, ChaCha8Rng,
101};
102
103/// ChaCha with 20 rounds
104pub type ChaChaRng = ChaCha20Rng;
105/// ChaCha with 20 rounds, low-level interface
106pub type ChaChaCore = ChaCha20Core;
rand_chacha/lib.rs

rand_chacha/
lib.rs
