Tracking Issue for secure random data generation in `std`

View all comments

Feature gate: #![feature(random)]

This is a tracking issue for secure random data generation support in std.

Central to this feature is the RandomSource trait inside core::random, which generates random bytes. std also exposes the platform's secure random number generator via the DefaultRandomSource type. There is a Distribution<T> trait for distributions that can sample random values of a specific type, and a random function for convenience to allow things like random(1..=6).

Public API

// core::random

pub trait Rng {
    fn fill_bytes(&mut self, bytes: &mut [u8]);
}

impl<'a, R: Rng + ?Sized> Rng for &'a mut R { ... }

pub trait Distribution<T> {
    fn sample(&self, source: &mut (impl Rng + ?Sized)) -> T;
}

impl Distribution<bool> for RangeFull { ... }
impl Distribution</* all integer types */> for RangeFull { ... }
impl Distribution</* all integer types */> for core::range::RangeInclusive<_> { ... }

// std::random (additionally)

pub struct SystemRng;

impl Rng for SystemRng { ... }

pub fn random<T>(dist: impl Distribution<T>) -> T;

Steps / History

• ACP: https://github.com/rust-lang/libs-team/issues/393
• Implementation
  • #129201
  • #143710 (API rework adding Distribution<T>)
  • #157539
  • #159435
  • #159592
  • #160205
• FCPs^1 and stabilization PRs
  • #157168

Unresolved Questions

• Naming: the ACP used gen_bytes and DefaultRng, the implementation PR uses fill_bytes and DefaultRandomSource (see arguments pro gen_bytes and pro fill_bytes)
• Concerns listed at https://github.com/rust-lang/libs-team/issues/393#issuecomment-2563932047 should be addressed

Start by reading the core::random and std::random API sections, then inspect the remaining implementation item #160205 and stabilization PR #157168. The issue's done state is completion of the listed implementation, resolution of the naming and other unresolved concerns, and the FCP and stabilization work.