blob: 6c8b5ba800c46966e3800e9f7458828a128954c1 [file]
// Licensed under the Apache-2.0 license
// SPDX-License-Identifier: Apache-2.0
//! # Random Number Generator HAL Traits
//!
//! This module provides blocking Hardware Abstraction Layer (HAL) traits for
//! cryptographically secure random number generators.
//!
//! ## Key Components
//!
//! - `CryptoRng` - Trait for filling a buffer with random bytes that are
//! suitable for keys and nonces
//! - `RandCore` - Adapter that implements the `rand_core` traits for a
//! `CryptoRng`
//!
//! ## Scope
//!
//! The HAL has no trait for generators that are not cryptographically
//! secure.
//!
//! The traits cover generating random bytes. A driver sets up its hardware
//! in its constructor: for example, it enables an entropy source or
//! instantiates a DRBG. Reseeding and mixing in additional input are not part
//! of these traits, because not every generator supports them.
//!
//! ## Example Usage
//!
//! ```rust
//! use openprot_hal_blocking::rng::{CryptoRng, Error, ErrorKind, ErrorType};
//!
//! fn nonce<R: CryptoRng>(rng: &mut R) -> Result<[u8; 32], ErrorKind> {
//! let mut nonce = [0; 32];
//! rng.fill(&mut nonce).map_err(|error| error.kind())?;
//! Ok(nonce)
//! }
//! # struct Counter(u8);
//! # impl ErrorType for Counter { type Error = core::convert::Infallible; }
//! # impl CryptoRng for Counter {
//! # fn fill(&mut self, dest: &mut [u8]) -> Result<(), Self::Error> {
//! # dest.iter_mut().for_each(|byte| { self.0 = self.0.wrapping_add(1); *byte = self.0; });
//! # Ok(())
//! # }
//! # }
//! # assert_eq!(nonce(&mut Counter(0)).unwrap()[..3], [1, 2, 3]);
//! ```
use core::fmt;
/// Error kind.
///
/// A common set of random number generator errors. Generic code can act on
/// these kinds without knowing the error type of an implementation.
#[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)]
#[non_exhaustive]
pub enum ErrorKind {
/// The generator has not been enabled, instantiated or seeded.
NotInitialized,
/// The generator is in use and cannot serve the request.
Busy,
/// The entropy source failed a health test, or the output does not have
/// the required quality.
EntropyFailure,
/// The generator must be reseeded before it can produce more output.
ReseedRequired,
/// The generator did not produce output in time.
Timeout,
/// General hardware failure.
HardwareFailure,
/// Insufficient permissions to use the generator.
PermissionDenied,
}
impl fmt::Display for ErrorKind {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::NotInitialized => write!(f, "random number generator not initialized"),
Self::Busy => write!(f, "random number generator is busy"),
Self::EntropyFailure => write!(f, "entropy source failure"),
Self::ReseedRequired => write!(f, "random number generator must be reseeded"),
Self::Timeout => write!(f, "random number generator timed out"),
Self::HardwareFailure => write!(f, "random number generator hardware failure"),
Self::PermissionDenied => write!(f, "insufficient permissions to access hardware"),
}
}
}
/// Trait for random number generator errors.
///
/// Implementations define their own error types and map them to an
/// [`ErrorKind`], on which generic code can act.
pub trait Error: fmt::Debug {
/// Converts the error to a generic error kind.
fn kind(&self) -> ErrorKind;
}
impl Error for core::convert::Infallible {
fn kind(&self) -> ErrorKind {
match *self {}
}
}
/// Trait for types that have an associated error type.
pub trait ErrorType {
/// Error type.
type Error: Error;
}
impl<T: ErrorType + ?Sized> ErrorType for &mut T {
type Error = T::Error;
}
/// A random number generator whose output is suitable for keys, nonces and
/// other secrets.
///
/// The output of such a generator is unpredictable to an attacker who knows
/// the earlier output. An example is a NIST SP 800-90A DRBG that is seeded
/// from a health-tested entropy source. A driver for a raw entropy source
/// that has no conditioning or health tests must not implement this trait.
///
/// The requirement is the same as that of `rand_core::CryptoRng`.
pub trait CryptoRng: ErrorType {
/// Fills `dest` with random bytes.
///
/// `dest` can have any length, including zero. An implementation whose
/// hardware produces a fixed or limited number of bytes at a time makes
/// as many requests as it needs. The call blocks until the hardware has
/// produced the bytes.
///
/// # Errors
///
/// After an error the contents of `dest` are unspecified and must not be
/// used as random bytes.
fn fill(&mut self, dest: &mut [u8]) -> Result<(), Self::Error>;
}
impl<T: CryptoRng + ?Sized> CryptoRng for &mut T {
fn fill(&mut self, dest: &mut [u8]) -> Result<(), Self::Error> {
T::fill(self, dest)
}
}
/// Adapter that implements `rand_core::TryRngCore` and
/// `rand_core::TryCryptoRng` for a [`CryptoRng`].
///
/// A [`CryptoRng`] can fail, so the adapter does not implement the
/// infallible `rand_core::RngCore`. Code that needs `RngCore` can call
/// `rand_core::TryRngCore::unwrap_err` on the adapter, which panics on an
/// error.
///
/// `RandCore::new(&mut rng)` wraps a borrowed generator.
///
/// Each `try_next_u32` or `try_next_u64` call makes one [`CryptoRng::fill`]
/// call, which is slow when each fill needs a hardware request.
#[derive(Debug)]
pub struct RandCore<R>(R);
impl<R: CryptoRng> RandCore<R> {
/// Wraps `rng`.
pub fn new(rng: R) -> Self {
Self(rng)
}
/// Returns the wrapped generator.
pub fn into_inner(self) -> R {
self.0
}
}
/// The error of a [`RandCore`]. It wraps the error of the generator.
#[derive(Debug, Copy, Clone, Eq, PartialEq)]
pub struct RandCoreError<E>(pub E);
impl<E: Error> fmt::Display for RandCoreError<E> {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
self.0.kind().fmt(f)
}
}
impl<R: CryptoRng> rand_core::TryRngCore for RandCore<R> {
type Error = RandCoreError<R::Error>;
fn try_next_u32(&mut self) -> Result<u32, Self::Error> {
let mut bytes = [0; 4];
self.try_fill_bytes(&mut bytes)?;
Ok(u32::from_le_bytes(bytes))
}
fn try_next_u64(&mut self) -> Result<u64, Self::Error> {
let mut bytes = [0; 8];
self.try_fill_bytes(&mut bytes)?;
Ok(u64::from_le_bytes(bytes))
}
fn try_fill_bytes(&mut self, dst: &mut [u8]) -> Result<(), Self::Error> {
self.0.fill(dst).map_err(RandCoreError)
}
}
impl<R: CryptoRng> rand_core::TryCryptoRng for RandCore<R> {}
#[cfg(test)]
mod tests {
use super::*;
use rand_core::TryRngCore;
/// Produces the bytes 1, 2, 3 and so on, and fails when `fail` is set.
struct Counter {
next: u8,
fail: bool,
}
#[derive(Debug, PartialEq)]
struct Failed;
impl Error for Failed {
fn kind(&self) -> ErrorKind {
ErrorKind::EntropyFailure
}
}
impl ErrorType for Counter {
type Error = Failed;
}
impl CryptoRng for Counter {
fn fill(&mut self, dest: &mut [u8]) -> Result<(), Self::Error> {
if self.fail {
return Err(Failed);
}
for byte in dest {
self.next = self.next.wrapping_add(1);
*byte = self.next;
}
Ok(())
}
}
fn counter() -> Counter {
Counter {
next: 0,
fail: false,
}
}
fn require_crypto<R: rand_core::TryCryptoRng>(_: &R) {}
#[test]
fn rand_core_adapter_reads_little_endian() {
let mut rng = RandCore::new(counter());
require_crypto(&rng);
assert_eq!(rng.try_next_u32(), Ok(0x0403_0201));
assert_eq!(rng.try_next_u64(), Ok(0x0c0b_0a09_0807_0605));
let mut bytes = [0; 3];
assert_eq!(rng.try_fill_bytes(&mut bytes), Ok(()));
assert_eq!(bytes, [13, 14, 15]);
assert_eq!(rng.into_inner().next, 15);
}
#[test]
fn rand_core_adapter_borrows() {
let mut inner = counter();
let mut rng = RandCore::new(&mut inner);
require_crypto(&rng);
assert_eq!(rng.try_next_u32(), Ok(0x0403_0201));
assert_eq!(inner.next, 4);
}
#[test]
fn rand_core_adapter_returns_the_error() {
let mut rng = RandCore::new(Counter {
next: 0,
fail: true,
});
let error = rng.try_next_u32().unwrap_err();
assert_eq!(error, RandCoreError(Failed));
assert_eq!(error.0.kind(), ErrorKind::EntropyFailure);
}
}