Debian Codegraph @

.cargo/vendor/rand_chacha/src/lib.rs

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