Add getrandom_uninit_slice(dest: &mut [MaybeUninit<u8>]) -> ....

Add a public API for filling an `&mut [MaybeUninit<u8>]`. This will primarily
serve as the building block for more typeful APIs for constructing random
arrays.

Increase the MSRV to 1.36, as `MaybeUninit` was added in that release.

Fixes #226.

Author: briansmith

.github/workflows/tests.yml

@@ -44,7 +44,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, windows-latest]
-        toolchain: [nightly, beta, stable, 1.34]
+        toolchain: [nightly, beta, stable, 1.36]
         # Only Test macOS on stable to reduce macOS CI jobs
         include:
           - os: macos-latest

CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## Unreleased
+### Added
+- `getrandom_uninit_slice` [#291]
+
+### Breaking Changes
+- Update MSRV to 1.36 [#291]
+
+[#291]: https://github.com/rust-random/getrandom/pull/291
+
 ## [0.2.7] - 2022-06-14
 ### Changed
 - Update `wasi` dependency to `0.11` [#253]

README.md

@@ -52,7 +52,7 @@ crate features, WASM support and Custom RNGs see the
 
 ## Minimum Supported Rust Version
 
-This crate requires Rust 1.34.0 or later.
+This crate requires Rust 1.36.0 or later.
 
 # License
 

benches/mod.rs

@@ -3,6 +3,7 @@ extern crate test;
 
 use std::{
     alloc::{alloc_zeroed, dealloc, Layout},
+    mem::{self, MaybeUninit},
     ptr::NonNull,
 };
 
@@ -59,6 +60,20 @@ fn bench_with_init<const N: usize>(b: &mut test::Bencher) {
     b.bytes = N as u64;
 }
 
+// Used to benchmark the benefit of `getrandom_uninit` compared to
+// zero-initializing a buffer and then using `getrandom` (`bench_with_init`
+// above).
+#[inline(always)]
+fn bench_uninit<const N: usize>(b: &mut test::Bencher) {
+    let mut ab = AlignedBuffer::<N>::new();
+    let buf = ab.buf();
+    // SAFETY: `buf` doesn't escape this scope.
+    let buf = unsafe { slice_as_uninit_mut(buf) };
+    b.iter(|| {
+        let _ = getrandom::getrandom_uninit_slice(buf);
+    })
+}
+
 // 32 bytes (256-bit) is the seed sized used for rand::thread_rng
 const SEED: usize = 32;
 // Common size of a page, 4 KiB
@@ -74,6 +89,10 @@ fn bench_seed(b: &mut test::Bencher) {
 fn bench_seed_init(b: &mut test::Bencher) {
     bench_with_init::<SEED>(b);
 }
+#[bench]
+fn bench_seed_uninit(b: &mut test::Bencher) {
+    bench_uninit::<SEED>(b);
+}
 
 #[bench]
 fn bench_page(b: &mut test::Bencher) {
@@ -83,6 +102,10 @@ fn bench_page(b: &mut test::Bencher) {
 fn bench_page_init(b: &mut test::Bencher) {
     bench_with_init::<PAGE>(b);
 }
+#[bench]
+fn bench_page_uninit(b: &mut test::Bencher) {
+    bench_uninit::<PAGE>(b);
+}
 
 #[bench]
 fn bench_large(b: &mut test::Bencher) {
@@ -92,3 +115,14 @@ fn bench_large(b: &mut test::Bencher) {
 fn bench_large_init(b: &mut test::Bencher) {
     bench_with_init::<LARGE>(b);
 }
+#[bench]
+fn bench_large_uninit(b: &mut test::Bencher) {
+    bench_uninit::<LARGE>(b);
+}
+
+// TODO: Safety note.
+#[inline(always)]
+unsafe fn slice_as_uninit_mut<T>(slice: &mut [T]) -> &mut [MaybeUninit<T>] {
+    // SAFETY: `MaybeUninit<T>` is guaranteed to be layout-compatible with `T`.
+    mem::transmute(slice)
+}

src/3ds.rs

@@ -9,8 +9,9 @@
 //! Implementation for Nintendo 3DS
 use crate::util_libc::sys_fill_exact;
 use crate::Error;
+use core::mem::MaybeUninit;
 
-pub fn getrandom_inner(dest: &mut [u8]) -> Result<(), Error> {
+pub fn getrandom_inner(dest: &mut [MaybeUninit<u8>]) -> Result<(), Error> {
     sys_fill_exact(dest, |buf| unsafe {
         libc::getrandom(buf.as_mut_ptr() as *mut libc::c_void, buf.len(), 0)
     })

src/bsd_arandom.rs

@@ -8,9 +8,9 @@
 
 //! Implementation for FreeBSD and NetBSD
 use crate::{util_libc::sys_fill_exact, Error};
-use core::ptr;
+use core::{mem::MaybeUninit, ptr};
 
-fn kern_arnd(buf: &mut [u8]) -> libc::ssize_t {
+fn kern_arnd(buf: &mut [MaybeUninit<u8>]) -> libc::ssize_t {
     static MIB: [libc::c_int; 2] = [libc::CTL_KERN, libc::KERN_ARND];
     let mut len = buf.len();
     let ret = unsafe {
@@ -30,18 +30,20 @@ fn kern_arnd(buf: &mut [u8]) -> libc::ssize_t {
     }
 }
 
-pub fn getrandom_inner(dest: &mut [u8]) -> Result<(), Error> {
+pub fn getrandom_inner(dest: &mut [MaybeUninit<u8>]) -> Result<(), Error> {
     // getrandom(2) was introduced in FreeBSD 12.0 and NetBSD 10.0
     #[cfg(target_os = "freebsd")]
     {
-        use crate::util_libc::Weak;
+        use crate::{util::uninit_slice_as_mut_ptr, util_libc::Weak};
         static GETRANDOM: Weak = unsafe { Weak::new("getrandom\0") };
         type GetRandomFn =
             unsafe extern "C" fn(*mut u8, libc::size_t, libc::c_uint) -> libc::ssize_t;
 
         if let Some(fptr) = GETRANDOM.ptr() {
             let func: GetRandomFn = unsafe { core::mem::transmute(fptr) };
-            return sys_fill_exact(dest, |buf| unsafe { func(buf.as_mut_ptr(), buf.len(), 0) });
+            return sys_fill_exact(dest, |buf| unsafe {
+                func(uninit_slice_as_mut_ptr(buf), buf.len(), 0)
+            });
         }
     }
     // Both FreeBSD and NetBSD will only return up to 256 bytes at a time, and

src/custom.rs

@@ -7,8 +7,8 @@
 // except according to those terms.
 
 //! An implementation which calls out to an externally defined function.
-use crate::Error;
-use core::num::NonZeroU32;
+use crate::{util::uninit_slice_fill_zero, Error};
+use core::{mem::MaybeUninit, num::NonZeroU32};
 
 /// Register a function to be invoked by `getrandom` on unsupported targets.
 ///
@@ -90,10 +90,16 @@ macro_rules! register_custom_getrandom {
 }
 
 #[allow(dead_code)]
-pub fn getrandom_inner(dest: &mut [u8]) -> Result<(), Error> {
+pub fn getrandom_inner(dest: &mut [MaybeUninit<u8>]) -> Result<(), Error> {
     extern "C" {
         fn __getrandom_custom(dest: *mut u8, len: usize) -> u32;
     }
+    // Previously we always passed a valid, initialized slice to
+    // `__getrandom_custom`. Ensure `dest` has been initialized for backward
+    // compatibility with implementations that rely on that (e.g. Rust
+    // implementations that construct a `&mut [u8]` slice from `dest` and
+    // `len`).
+    let dest = uninit_slice_fill_zero(dest);
     let ret = unsafe { __getrandom_custom(dest.as_mut_ptr(), dest.len()) };
     match NonZeroU32::new(ret) {
         None => Ok(()),

src/dragonfly.rs

@@ -12,8 +12,9 @@ use crate::{
     util_libc::{sys_fill_exact, Weak},
     Error,
 };
+use std::mem::MaybeUninit;
 
-pub fn getrandom_inner(dest: &mut [u8]) -> Result<(), Error> {
+pub fn getrandom_inner(dest: &mut [MaybeUninit<u8>]) -> Result<(), Error> {
     static GETRANDOM: Weak = unsafe { Weak::new("getrandom\0") };
     type GetRandomFn = unsafe extern "C" fn(*mut u8, libc::size_t, libc::c_uint) -> libc::ssize_t;
 

src/espidf.rs

@@ -8,13 +8,13 @@
 
 //! Implementation for ESP-IDF
 use crate::Error;
-use core::ffi::c_void;
+use core::{ffi::c_void, mem::MaybeUninit};
 
 extern "C" {
     fn esp_fill_random(buf: *mut c_void, len: usize) -> u32;
 }
 
-pub fn getrandom_inner(dest: &mut [u8]) -> Result<(), Error> {
+pub fn getrandom_inner(dest: &mut [MaybeUninit<u8>]) -> Result<(), Error> {
     // Not that NOT enabling WiFi, BT, or the voltage noise entropy source (via `bootloader_random_enable`)
     // will cause ESP-IDF to return pseudo-random numbers based on the voltage noise entropy, after the initial boot process:
     // https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/random.html

src/fuchsia.rs

@@ -7,14 +7,15 @@
 // except according to those terms.
 
 //! Implementation for Fuchsia Zircon
-use crate::Error;
+use crate::{util::uninit_slice_as_mut_ptr, Error};
+use core::mem::MaybeUninit;
 
 #[link(name = "zircon")]
 extern "C" {
     fn zx_cprng_draw(buffer: *mut u8, length: usize);
 }
 
-pub fn getrandom_inner(dest: &mut [u8]) -> Result<(), Error> {
-    unsafe { zx_cprng_draw(dest.as_mut_ptr(), dest.len()) }
+pub fn getrandom_inner(dest: &mut [MaybeUninit<u8>]) -> Result<(), Error> {
+    unsafe { zx_cprng_draw(uninit_slice_as_mut_ptr(dest), dest.len()) }
     Ok(())
 }