52 lines
2.6 KiB
Rust
52 lines
2.6 KiB
Rust
// Copyright 2017 The Rust Project Developers. See the COPYRIGHT
|
|
// file at the top-level directory of this distribution and at
|
|
// http://rust-lang.org/COPYRIGHT.
|
|
//
|
|
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
|
|
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
|
|
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
|
|
// option. This file may not be copied, modified, or distributed
|
|
// except according to those terms.
|
|
|
|
//! Pseudo random number generators are algorithms to produce *apparently
|
|
//! random* numbers deterministically, and usually fairly quickly.
|
|
//!
|
|
//! So long as the algorithm is computationally secure, is initialised with
|
|
//! sufficient entropy (i.e. unknown by an attacker), and its internal state is
|
|
//! also protected (unknown to an attacker), the output will also be
|
|
//! *computationally secure*. Computationally Secure Pseudo Random Number
|
|
//! Generators (CSPRNGs) are thus suitable sources of random numbers for
|
|
//! cryptography. There are a couple of gotchas here, however. First, the seed
|
|
//! used for initialisation must be unknown. Usually this should be provided by
|
|
//! the operating system and should usually be secure, however this may not
|
|
//! always be the case (especially soon after startup). Second, user-space
|
|
//! memory may be vulnerable, for example when written to swap space, and after
|
|
//! forking a child process should reinitialise any user-space PRNGs. For this
|
|
//! reason it may be preferable to source random numbers directly from the OS
|
|
//! for cryptographic applications.
|
|
//!
|
|
//! PRNGs are also widely used for non-cryptographic uses: randomised
|
|
//! algorithms, simulations, games. In these applications it is usually not
|
|
//! important for numbers to be cryptographically *unguessable*, but even
|
|
//! distribution and independence from other samples (from the point of view
|
|
//! of someone unaware of the algorithm used, at least) may still be important.
|
|
//! Good PRNGs should satisfy these properties, but do not take them for
|
|
//! granted; Wikipedia's article on
|
|
//! [Pseudorandom number generators](https://en.wikipedia.org/wiki/Pseudorandom_number_generator)
|
|
//! provides some background on this topic.
|
|
//!
|
|
//! Care should be taken when seeding (initialising) PRNGs. Some PRNGs have
|
|
//! short periods for some seeds. If one PRNG is seeded from another using the
|
|
//! same algorithm, it is possible that both will yield the same sequence of
|
|
//! values (with some lag).
|
|
|
|
mod chacha;
|
|
mod isaac;
|
|
mod isaac64;
|
|
mod xorshift;
|
|
|
|
pub use self::chacha::ChaChaRng;
|
|
pub use self::isaac::IsaacRng;
|
|
pub use self::isaac64::Isaac64Rng;
|
|
pub use self::xorshift::XorShiftRng;
|