bouncycastle_rng/
lib.rs

1//! RNG objects for cryptographically secure random number generation.
2//!
3//! This crate provides the implementations of the deterministic random bit generator (DRBG) algorithms
4//! which, together with a strong entropy source, form the basis of cryptographic random number generation.
5//!
6//! Here's the basic way to get some random bytes:
7//!
8//! ```
9//! use bouncycastle_core::traits::RNG;
10//! use bouncycastle_rng as rng;
11//!
12//! let random_bytes = rng::DefaultRNG::default().next_bytes(32);
13//! ```
14//! This is secure because `::default()` seeds the RNG from the OS, configured for general use.
15//!
16//! **WARNING: most people should stop reading here and should not be mucking around with the internals of RNGs.
17//! This crate contains dragons and other horrible things. 🐉🐍🐜**
18//!
19//! # 🚨🚨🚨Security Warning 🚨🚨🚨
20//!
21//! Misuse of the objects in this crate can lead to output which may appear random, but
22//! is in fact completely deterministic (ie multiple runs of your application will give the same outputs)
23//! and will therefore compromise any cryptographic operation built on top of those outputs.
24//! You should only be here if your application requires direct control over configuring the internals of the DRBG.
25//!
26//! This crate contains the [Sp80090ADrbg] trait, which is intentionally defined here and not in [bouncycastle_core::traits]
27//! since misuse of [Sp80090ADrbg::instantiate] can completely undermine the security of your entire
28//! cryptographic application.
29
30#![forbid(unsafe_code)]
31#![allow(incomplete_features)] // Need this because generic_const_exprs is currently experimental.
32#![feature(generic_const_exprs)]
33
34use crate::hash_drbg80090a::{
35    HashDRBG80090A, HashDRBG80090AParams_SHA256, HashDRBG80090AParams_SHA512,
36};
37use bouncycastle_core::errors::RNGError;
38use bouncycastle_core::key_material::KeyMaterialTrait;
39use bouncycastle_core::traits::SecurityStrength;
40
41// needed for docs
42#[allow(unused_imports)]
43use bouncycastle_core::key_material::KeyType;
44// end doc-only imports
45
46pub mod hash_drbg80090a;
47
48/*** String constants ***/
49pub const HASH_DRBG_SHA256_NAME: &str = "HashDRBG-SHA256";
50pub const HASH_DRBG_SHA512_NAME: &str = "HashDRBG-SHA512";
51
52/*** pub types ***/
53#[allow(non_camel_case_types)]
54pub type HashDRBG_SHA256 = HashDRBG80090A<HashDRBG80090AParams_SHA256>;
55#[allow(non_camel_case_types)]
56pub type HashDRBG_SHA512 = HashDRBG80090A<HashDRBG80090AParams_SHA512>;
57
58/*** Defaults ***/
59pub type DefaultRNG = HashDRBG_SHA512;
60pub type Default128BitRNG = HashDRBG_SHA256;
61pub type Default256BitRNG = HashDRBG_SHA512;
62
63/// Implements the five functions specified in SP 800-90A section 7.4 are instantate, generate, reseed, uninstantiate, and health_test.
64/// Note: this function implements Rust's Drop on the sensitive working state in place of the explicit Uninstantiate function listed in SP 800-90Ar1.
65pub trait Sp80090ADrbg {
66    /// The input KeyMaterial must be of type [KeyType::Seed].
67    ///
68    /// """
69    /// 8.6.3 Entropy Requirements for the Entropy Input
70    /// The entropy input shall have entropy that is equal to or greater than the security strength of the
71    /// instantiation. Additional entropy may be provided in the nonce or the optional personalization
72    /// string during instantiation, or in the additional input during reseeding and generation, but this is
73    /// not required and does not increase the “official” security strength of the DRBG instantiation that
74    /// is recorded in the internal state.
75    ///
76    /// 8.6.4 Seed Length
77    /// The minimum length of the seed depends on the DRBG mechanism and the security strength
78    /// required by the consuming application, but shall be at least the number of bits of entropy
79    /// required.
80    /// """
81    ///
82    /// This function takes ownership of the seed KeyMaterial object, to reduce the likelihood of its reuse in a second function call.
83    ///
84    /// There is no entropy requirement on the nonce, but it is expected as a KeyMaterial so that it
85    /// benefits from the secure erasure and logging protections in the KeyMaterial object.
86    fn instantiate(
87        &mut self,
88        prediction_resistance: bool,
89        seed: impl KeyMaterialTrait,
90        nonce: &impl KeyMaterialTrait,
91        personalization_string: &[u8],
92        security_strength: SecurityStrength,
93    ) -> Result<(), RNGError>;
94
95    /// Reseeds the DRBG with the provided seed.
96    /// TODO: this needs to be thought out to take some sort of EntropySource object that'll work well with DRBGs that require frequent reseeding.
97    fn reseed(
98        &mut self,
99        seed: &impl KeyMaterialTrait,
100        additional_input: &[u8],
101    ) -> Result<(), RNGError>;
102
103    /// Note that for a calling application to be in compliance with SP 800-90A, this requirement
104    /// from section 8.4 must be met:
105    ///    "The pseudorandom bits returned from a DRBG shall not be used for any
106    /// application that requires a higher security strength than the DRBG is instantiated to support. The
107    /// security strength provided in these returned bits is the minimum of the security strength
108    /// supported by the DRBG and the length of the bit string returned"
109    ///
110    /// As required by SP 800-90A section 8.4, `len` cannot exceed the initialized [SecurityStrength]
111    /// of this instance, although multiple calls to this function can be made, in which case it is the
112    /// application's responsibility to track that it is not expecting more entropy than the [SecurityStrength]
113    /// to which this instance was instantiated. For example, extracting two 128-bit values from an instance
114    /// instantiated to [SecurityStrength::_128bit] and then combining tem to form an AES-256 key would likely
115    /// not pass FIPS certification.
116    ///
117    /// Throws a [RNGError::InsufficientSeedEntropy] if `len` exceeds [SecurityStrength].
118    fn generate(&mut self, additional_input: &[u8], len: usize) -> Result<Vec<u8>, RNGError>;
119
120    /// As per [Sp80090ADrbg::generate], but writes to the provided output slice.
121    /// The output slice is filled.
122    /// Throws a [RNGError::InsufficientSeedEntropy] if the length of the output slice exceeds [SecurityStrength].
123    /// Retruns the number of bits output.
124    fn generate_out(&mut self, additional_input: &[u8], out: &mut [u8]) -> Result<usize, RNGError>;
125
126    /// As per [Sp80090ADrbg::generate], but writes to the provided KeyMaterial.
127    /// The output [KeyMaterialTrait] is filled to capacity.
128    /// Throws a [RNGError::InsufficientSeedEntropy] if the capacity of the output KeyMaterial exceeds [SecurityStrength].
129    /// Retruns the number of bits output.
130    fn generate_keymaterial_out(
131        &mut self,
132        additional_input: &[u8],
133        out: &mut impl KeyMaterialTrait,
134    ) -> Result<usize, RNGError>;
135
136    // TODO -- implement FIPS health tests
137    // fn health_test(&mut self) -> Result<bool, RNGError>;
138}
bouncycastle_rng/lib.rs

bouncycastle_rng/
lib.rs
