From 9a6ed59fe4268ef22021bf58a21e2a5210583022 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=90=D1=80=D1=82=D1=91=D0=BC=20=D0=9F=D0=B0=D0=B2=D0=BB?= =?UTF-8?q?=D0=BE=D0=B2=20=5BArtyom=20Pavlov=5D?= Date: Mon, 21 Oct 2024 14:52:04 +0300 Subject: [PATCH] Rename `getrandom(_uninit)` to `fill(_uninit)` --- README.md | 2 +- benches/buffer.rs | 4 ++-- src/apple-other.rs | 2 +- src/custom.rs | 2 +- src/esp_idf.rs | 2 +- src/fuchsia.rs | 2 +- src/getentropy.rs | 2 +- src/getrandom.rs | 2 +- src/hermit.rs | 2 +- src/lib.rs | 37 ++++++++++++++++++------------ src/linux_android.rs | 2 +- src/linux_android_with_fallback.rs | 4 ++-- src/linux_rustix.rs | 2 +- src/netbsd.rs | 2 +- src/rdrand.rs | 2 +- src/rndr.rs | 2 +- src/solaris.rs | 2 +- src/solid.rs | 2 +- src/use_file.rs | 2 +- src/vxworks.rs | 2 +- src/wasi.rs | 4 ++-- src/wasm_js.rs | 2 +- src/windows.rs | 2 +- src/windows7.rs | 2 +- tests/mod.rs | 30 ++++++++++++------------ 25 files changed, 63 insertions(+), 56 deletions(-) diff --git a/README.md b/README.md index ef8a6ce2..7393dbe9 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,7 @@ Then invoke the `getrandom` function: ```rust fn get_random_buf() -> Result<[u8; 32], getrandom::Error> { let mut buf = [0u8; 32]; - getrandom::getrandom(&mut buf)?; + getrandom::fill(&mut buf)?; Ok(buf) } ``` diff --git a/benches/buffer.rs b/benches/buffer.rs index 303bc3e4..fb0a0b92 100644 --- a/benches/buffer.rs +++ b/benches/buffer.rs @@ -7,7 +7,7 @@ use std::mem::MaybeUninit; #[inline(always)] fn bench_getrandom() { let mut buf = [0u8; N]; - getrandom::getrandom(&mut buf).unwrap(); + getrandom::fill(&mut buf).unwrap(); test::black_box(&buf[..]); } @@ -15,7 +15,7 @@ fn bench_getrandom() { #[inline(always)] fn bench_getrandom_uninit() { let mut uninit = [MaybeUninit::uninit(); N]; - let buf: &[u8] = getrandom::getrandom_uninit(&mut uninit).unwrap(); + let buf: &[u8] = getrandom::fill_uninit(&mut uninit).unwrap(); test::black_box(buf); } diff --git a/src/apple-other.rs b/src/apple-other.rs index 6c761494..1990523f 100644 --- a/src/apple-other.rs +++ b/src/apple-other.rs @@ -2,7 +2,7 @@ use crate::Error; use core::{ffi::c_void, mem::MaybeUninit}; -pub fn getrandom_inner(dest: &mut [MaybeUninit]) -> Result<(), Error> { +pub fn fill_inner(dest: &mut [MaybeUninit]) -> Result<(), Error> { let dst_ptr = dest.as_mut_ptr().cast::(); let ret = unsafe { libc::CCRandomGenerateBytes(dst_ptr, dest.len()) }; if ret == libc::kCCSuccess { diff --git a/src/custom.rs b/src/custom.rs index c3e94349..e97d3293 100644 --- a/src/custom.rs +++ b/src/custom.rs @@ -2,7 +2,7 @@ use crate::Error; use core::mem::MaybeUninit; -pub fn getrandom_inner(dest: &mut [MaybeUninit]) -> Result<(), Error> { +pub fn fill_inner(dest: &mut [MaybeUninit]) -> Result<(), Error> { extern "Rust" { fn __getrandom_v03_custom(dest: *mut u8, len: usize) -> Result<(), Error>; } diff --git a/src/esp_idf.rs b/src/esp_idf.rs index 75e81aaf..2df7b9aa 100644 --- a/src/esp_idf.rs +++ b/src/esp_idf.rs @@ -9,7 +9,7 @@ extern "C" { fn esp_fill_random(buf: *mut c_void, len: usize) -> u32; } -pub fn getrandom_inner(dest: &mut [MaybeUninit]) -> Result<(), Error> { +pub fn fill_inner(dest: &mut [MaybeUninit]) -> 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 diff --git a/src/fuchsia.rs b/src/fuchsia.rs index 22ae7796..b8e6de86 100644 --- a/src/fuchsia.rs +++ b/src/fuchsia.rs @@ -7,7 +7,7 @@ extern "C" { fn zx_cprng_draw(buffer: *mut u8, length: usize); } -pub fn getrandom_inner(dest: &mut [MaybeUninit]) -> Result<(), Error> { +pub fn fill_inner(dest: &mut [MaybeUninit]) -> Result<(), Error> { unsafe { zx_cprng_draw(dest.as_mut_ptr().cast::(), dest.len()) } Ok(()) } diff --git a/src/getentropy.rs b/src/getentropy.rs index eee47403..78c797e1 100644 --- a/src/getentropy.rs +++ b/src/getentropy.rs @@ -10,7 +10,7 @@ use crate::{util_libc::last_os_error, Error}; use core::{ffi::c_void, mem::MaybeUninit}; -pub fn getrandom_inner(dest: &mut [MaybeUninit]) -> Result<(), Error> { +pub fn fill_inner(dest: &mut [MaybeUninit]) -> Result<(), Error> { for chunk in dest.chunks_mut(256) { let ret = unsafe { libc::getentropy(chunk.as_mut_ptr().cast::(), chunk.len()) }; if ret != 0 { diff --git a/src/getrandom.rs b/src/getrandom.rs index 88c077c6..e0f463de 100644 --- a/src/getrandom.rs +++ b/src/getrandom.rs @@ -18,7 +18,7 @@ use crate::{util_libc::sys_fill_exact, Error}; use core::{ffi::c_void, mem::MaybeUninit}; -pub fn getrandom_inner(dest: &mut [MaybeUninit]) -> Result<(), Error> { +pub fn fill_inner(dest: &mut [MaybeUninit]) -> Result<(), Error> { sys_fill_exact(dest, |buf| unsafe { libc::getrandom(buf.as_mut_ptr().cast::(), buf.len(), 0) }) diff --git a/src/hermit.rs b/src/hermit.rs index 9dc9d8bd..594b330b 100644 --- a/src/hermit.rs +++ b/src/hermit.rs @@ -6,7 +6,7 @@ extern "C" { fn sys_read_entropy(buffer: *mut u8, length: usize, flags: u32) -> isize; } -pub fn getrandom_inner(mut dest: &mut [MaybeUninit]) -> Result<(), Error> { +pub fn fill_inner(mut dest: &mut [MaybeUninit]) -> Result<(), Error> { while !dest.is_empty() { let res = unsafe { sys_read_entropy(dest.as_mut_ptr().cast::(), dest.len(), 0) }; match res { diff --git a/src/lib.rs b/src/lib.rs index 0a2b2a31..d138c444 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -213,7 +213,7 @@ //! //! ## Sanitizer support //! -//! If your code uses `getrandom_uninit` and you use memory sanitizer +//! If your code uses [`fill_uninit`] and you use memory sanitizer //! (i.e. `-Zsanitizer=memory`), then you need to pass `getrandom_sanitize` //! configuration flag for `getrandom_uninit` to unpoison destination buffer. //! @@ -304,8 +304,8 @@ use crate::util::{slice_as_uninit_mut, slice_assume_init_mut}; // System-specific implementations. // -// These should all provide getrandom_inner with the signature -// `fn getrandom_inner(dest: &mut [MaybeUninit]) -> Result<(), Error>`. +// These should all provide fill_inner with the signature +// `fn fill_inner(dest: &mut [MaybeUninit]) -> Result<(), Error>`. // The function MUST fully initialize `dest` when `Ok(())` is returned. // The function MUST NOT ever write uninitialized bytes into `dest`, // regardless of what value it returns. @@ -442,8 +442,7 @@ cfg_if! { } } -/// Fill `dest` with random bytes from the system's preferred random number -/// source. +/// Fill `dest` with random bytes from the system's preferred random number source. /// /// This function returns an error on any failure, including partial reads. We /// make no guarantees regarding the contents of `dest` on error. If `dest` is @@ -455,17 +454,25 @@ cfg_if! { /// In general, `getrandom` will be fast enough for interactive usage, though /// significantly slower than a user-space CSPRNG; for the latter consider /// [`rand::thread_rng`](https://docs.rs/rand/*/rand/fn.thread_rng.html). +/// +/// # Examples +/// +/// ``` +/// let mut buf = [0u8; 32]; +/// getrandom::fill(&mut buf)?; +/// ``` #[inline] -pub fn getrandom(dest: &mut [u8]) -> Result<(), Error> { - // SAFETY: The `&mut MaybeUninit<_>` reference doesn't escape, and - // `getrandom_uninit` guarantees it will never de-initialize any part of - // `dest`. - getrandom_uninit(unsafe { slice_as_uninit_mut(dest) })?; +pub fn fill(dest: &mut [u8]) -> Result<(), Error> { + // SAFETY: The `&mut MaybeUninit<_>` reference doesn't escape, + // and `fill_uninit` guarantees it will never de-initialize + // any part of `dest`. + fill_uninit(unsafe { slice_as_uninit_mut(dest) })?; Ok(()) } -/// Version of the `getrandom` function which fills `dest` with random bytes -/// returns a mutable reference to those bytes. +/// Fill potentially uninitialized buffer `dest` with random bytes from +/// the system's preferred random number source and return a mutable +/// reference to those bytes. /// /// On successful completion this function is guaranteed to return a slice /// which points to the same memory as `dest` and has the same length. @@ -486,9 +493,9 @@ pub fn getrandom(dest: &mut [u8]) -> Result<(), Error> { /// # Ok(()) } /// ``` #[inline] -pub fn getrandom_uninit(dest: &mut [MaybeUninit]) -> Result<&mut [u8], Error> { +pub fn fill_uninit(dest: &mut [MaybeUninit]) -> Result<&mut [u8], Error> { if !dest.is_empty() { - imp::getrandom_inner(dest)?; + imp::fill_inner(dest)?; } #[cfg(getrandom_sanitize)] @@ -497,7 +504,7 @@ pub fn getrandom_uninit(dest: &mut [MaybeUninit]) -> Result<&mut [u8], Error fn __msan_unpoison(a: *mut core::ffi::c_void, size: usize); } - // SAFETY: `dest` has been fully initialized by `imp::getrandom_inner` + // SAFETY: `dest` has been fully initialized by `imp::fill_inner` // since it returned `Ok`. Ok(unsafe { #[cfg(getrandom_sanitize)] diff --git a/src/linux_android.rs b/src/linux_android.rs index 548401b2..a4dd4e26 100644 --- a/src/linux_android.rs +++ b/src/linux_android.rs @@ -5,7 +5,7 @@ use core::mem::MaybeUninit; #[cfg(not(any(target_os = "android", target_os = "linux")))] compile_error!("`linux_getrandom` backend can be enabled only for Linux/Android targets!"); -pub fn getrandom_inner(dest: &mut [MaybeUninit]) -> Result<(), Error> { +pub fn fill_inner(dest: &mut [MaybeUninit]) -> Result<(), Error> { util_libc::sys_fill_exact(dest, |buf| unsafe { libc::getrandom(buf.as_mut_ptr().cast(), buf.len(), 0) }) diff --git a/src/linux_android_with_fallback.rs b/src/linux_android_with_fallback.rs index dd401caa..53570d2f 100644 --- a/src/linux_android_with_fallback.rs +++ b/src/linux_android_with_fallback.rs @@ -52,10 +52,10 @@ fn init() -> NonNull { // prevent inlining of the fallback implementation #[inline(never)] fn use_file_fallback(dest: &mut [MaybeUninit]) -> Result<(), Error> { - use_file::getrandom_inner(dest) + use_file::fill_inner(dest) } -pub fn getrandom_inner(dest: &mut [MaybeUninit]) -> Result<(), Error> { +pub fn fill_inner(dest: &mut [MaybeUninit]) -> Result<(), Error> { // Despite being only a single atomic variable, we still cannot always use // Ordering::Relaxed, as we need to make sure a successful call to `init` // is "ordered before" any data read through the returned pointer (which diff --git a/src/linux_rustix.rs b/src/linux_rustix.rs index a286b20c..4fef3381 100644 --- a/src/linux_rustix.rs +++ b/src/linux_rustix.rs @@ -5,7 +5,7 @@ use rustix::rand::{getrandom_uninit, GetRandomFlags}; #[cfg(not(any(target_os = "android", target_os = "linux")))] compile_error!("`linux_rustix` backend can be enabled only for Linux/Android targets!"); -pub fn getrandom_inner(mut dest: &mut [MaybeUninit]) -> Result<(), Error> { +pub fn fill_inner(mut dest: &mut [MaybeUninit]) -> Result<(), Error> { loop { let res = getrandom_uninit(dest, GetRandomFlags::empty()).map(|(res, _)| res.len()); match res { diff --git a/src/netbsd.rs b/src/netbsd.rs index 10cb2e54..a96d353f 100644 --- a/src/netbsd.rs +++ b/src/netbsd.rs @@ -57,7 +57,7 @@ fn init() -> *mut c_void { ptr } -pub fn getrandom_inner(dest: &mut [MaybeUninit]) -> Result<(), Error> { +pub fn fill_inner(dest: &mut [MaybeUninit]) -> Result<(), Error> { // Despite being only a single atomic variable, we still cannot always use // Ordering::Relaxed, as we need to make sure a successful call to `init` // is "ordered before" any data read through the returned pointer (which diff --git a/src/rdrand.rs b/src/rdrand.rs index 68f9878c..2f2aed14 100644 --- a/src/rdrand.rs +++ b/src/rdrand.rs @@ -96,7 +96,7 @@ fn is_rdrand_good() -> bool { unsafe { self_test() } } -pub fn getrandom_inner(dest: &mut [MaybeUninit]) -> Result<(), Error> { +pub fn fill_inner(dest: &mut [MaybeUninit]) -> Result<(), Error> { static RDRAND_GOOD: LazyBool = LazyBool::new(); if !RDRAND_GOOD.unsync_init(is_rdrand_good) { return Err(Error::NO_RDRAND); diff --git a/src/rndr.rs b/src/rndr.rs index c670b53f..573fa9a4 100644 --- a/src/rndr.rs +++ b/src/rndr.rs @@ -101,7 +101,7 @@ fn is_rndr_available() -> bool { } } -pub fn getrandom_inner(dest: &mut [MaybeUninit]) -> Result<(), Error> { +pub fn fill_inner(dest: &mut [MaybeUninit]) -> Result<(), Error> { if is_rndr_available() { // SAFETY: after this point, we know the `rand` target feature is enabled unsafe { rndr_fill(dest).ok_or(Error::RNDR_FAILURE) } diff --git a/src/solaris.rs b/src/solaris.rs index 203000b0..f2470e8a 100644 --- a/src/solaris.rs +++ b/src/solaris.rs @@ -17,7 +17,7 @@ use core::{ffi::c_void, mem::MaybeUninit}; const MAX_BYTES: usize = 1024; -pub fn getrandom_inner(dest: &mut [MaybeUninit]) -> Result<(), Error> { +pub fn fill_inner(dest: &mut [MaybeUninit]) -> Result<(), Error> { for chunk in dest.chunks_mut(MAX_BYTES) { let ptr = chunk.as_mut_ptr().cast::(); let ret = unsafe { libc::getrandom(ptr, chunk.len(), libc::GRND_RANDOM) }; diff --git a/src/solid.rs b/src/solid.rs index 36f51caa..50bbe47e 100644 --- a/src/solid.rs +++ b/src/solid.rs @@ -6,7 +6,7 @@ extern "C" { pub fn SOLID_RNG_SampleRandomBytes(buffer: *mut u8, length: usize) -> i32; } -pub fn getrandom_inner(dest: &mut [MaybeUninit]) -> Result<(), Error> { +pub fn fill_inner(dest: &mut [MaybeUninit]) -> Result<(), Error> { let ret = unsafe { SOLID_RNG_SampleRandomBytes(dest.as_mut_ptr().cast::(), dest.len()) }; if ret >= 0 { Ok(()) diff --git a/src/use_file.rs b/src/use_file.rs index ff6b2236..45377572 100644 --- a/src/use_file.rs +++ b/src/use_file.rs @@ -37,7 +37,7 @@ const FD_ONGOING_INIT: libc::c_int = -2; // `Ordering::Acquire` to synchronize with it. static FD: AtomicI32 = AtomicI32::new(FD_UNINIT); -pub fn getrandom_inner(dest: &mut [MaybeUninit]) -> Result<(), Error> { +pub fn fill_inner(dest: &mut [MaybeUninit]) -> Result<(), Error> { let mut fd = FD.load(Ordering::Acquire); if fd == FD_UNINIT || fd == FD_ONGOING_INIT { fd = open_or_wait()?; diff --git a/src/vxworks.rs b/src/vxworks.rs index 58b6c962..6d8a4bf9 100644 --- a/src/vxworks.rs +++ b/src/vxworks.rs @@ -6,7 +6,7 @@ use core::{ sync::atomic::{AtomicBool, Ordering::Relaxed}, }; -pub fn getrandom_inner(dest: &mut [MaybeUninit]) -> Result<(), Error> { +pub fn fill_inner(dest: &mut [MaybeUninit]) -> Result<(), Error> { static RNG_INIT: AtomicBool = AtomicBool::new(false); while !RNG_INIT.load(Relaxed) { let ret = unsafe { libc::randSecure() }; diff --git a/src/wasi.rs b/src/wasi.rs index 9df9bf26..a1ecf004 100644 --- a/src/wasi.rs +++ b/src/wasi.rs @@ -12,7 +12,7 @@ compile_error!( ); #[cfg(target_env = "p1")] -pub fn getrandom_inner(dest: &mut [MaybeUninit]) -> Result<(), Error> { +pub fn fill_inner(dest: &mut [MaybeUninit]) -> Result<(), Error> { // This linking is vendored from the wasi crate: // https://docs.rs/wasi/0.11.0+wasi-snapshot-preview1/src/wasi/lib_generated.rs.html#2344-2350 #[link(wasm_import_module = "wasi_snapshot_preview1")] @@ -38,7 +38,7 @@ pub fn getrandom_inner(dest: &mut [MaybeUninit]) -> Result<(), Error> { } #[cfg(target_env = "p2")] -pub fn getrandom_inner(dest: &mut [MaybeUninit]) -> Result<(), Error> { +pub fn fill_inner(dest: &mut [MaybeUninit]) -> Result<(), Error> { use core::ptr::copy_nonoverlapping; use wasi::random::random::get_random_u64; diff --git a/src/wasm_js.rs b/src/wasm_js.rs index 026fa9ac..da70d5ad 100644 --- a/src/wasm_js.rs +++ b/src/wasm_js.rs @@ -30,7 +30,7 @@ thread_local!( static RNG_SOURCE: Result = getrandom_init(); ); -pub(crate) fn getrandom_inner(dest: &mut [MaybeUninit]) -> Result<(), Error> { +pub(crate) fn fill_inner(dest: &mut [MaybeUninit]) -> Result<(), Error> { RNG_SOURCE.with(|result| { let source = result.as_ref().map_err(|&e| e)?; diff --git a/src/windows.rs b/src/windows.rs index e44c4292..642206e7 100644 --- a/src/windows.rs +++ b/src/windows.rs @@ -31,7 +31,7 @@ windows_targets::link!("bcryptprimitives.dll" "system" fn ProcessPrng(pbdata: *m pub type BOOL = i32; pub const TRUE: BOOL = 1i32; -pub fn getrandom_inner(dest: &mut [MaybeUninit]) -> Result<(), Error> { +pub fn fill_inner(dest: &mut [MaybeUninit]) -> Result<(), Error> { // ProcessPrng should always return TRUE, but we check just in case. match unsafe { ProcessPrng(dest.as_mut_ptr().cast::(), dest.len()) } { TRUE => Ok(()), diff --git a/src/windows7.rs b/src/windows7.rs index 667bbf26..573ac881 100644 --- a/src/windows7.rs +++ b/src/windows7.rs @@ -23,7 +23,7 @@ extern "system" { type BOOLEAN = u8; const TRUE: BOOLEAN = 1u8; -pub fn getrandom_inner(dest: &mut [MaybeUninit]) -> Result<(), Error> { +pub fn fill_inner(dest: &mut [MaybeUninit]) -> Result<(), Error> { // Prevent overflow of u32 let chunk_size = usize::try_from(i32::MAX).expect("Windows does not support 16-bit targets"); for chunk in dest.chunks_mut(chunk_size) { diff --git a/tests/mod.rs b/tests/mod.rs index 47bc1b27..58e22951 100644 --- a/tests/mod.rs +++ b/tests/mod.rs @@ -1,5 +1,5 @@ use core::mem::MaybeUninit; -use getrandom::{getrandom, getrandom_uninit}; +use getrandom::{fill, fill_uninit}; #[cfg(getrandom_browser_test)] use wasm_bindgen_test::wasm_bindgen_test as test; @@ -9,8 +9,8 @@ wasm_bindgen_test::wasm_bindgen_test_configure!(run_in_browser); #[test] fn test_zero() { // Test that APIs are happy with zero-length requests - getrandom(&mut [0u8; 0]).unwrap(); - let res = getrandom_uninit(&mut []).unwrap(); + fill(&mut [0u8; 0]).unwrap(); + let res = fill_uninit(&mut []).unwrap(); assert!(res.is_empty()); } @@ -35,13 +35,13 @@ fn test_diff() { const N: usize = 1000; let mut v1 = [0u8; N]; let mut v2 = [0u8; N]; - getrandom(&mut v1).unwrap(); - getrandom(&mut v2).unwrap(); + fill(&mut v1).unwrap(); + fill(&mut v2).unwrap(); let mut t1 = uninit_vec(N); let mut t2 = uninit_vec(N); - let r1 = getrandom_uninit(&mut t1).unwrap(); - let r2 = getrandom_uninit(&mut t2).unwrap(); + let r1 = fill_uninit(&mut t1).unwrap(); + let r2 = fill_uninit(&mut t2).unwrap(); assert_eq!(r1.len(), N); assert_eq!(r2.len(), N); @@ -71,8 +71,8 @@ fn test_small() { let s1 = &mut buf1[..size]; let s2 = &mut buf2[..size]; - getrandom(s1).unwrap(); - getrandom(s2).unwrap(); + fill(s1).unwrap(); + fill(s2).unwrap(); num_bytes += size; diff_bits += num_diff_bits(s1, s2); @@ -99,8 +99,8 @@ fn test_small_uninit() { let s1 = &mut buf1[..size]; let s2 = &mut buf2[..size]; - let r1 = getrandom_uninit(s1).unwrap(); - let r2 = getrandom_uninit(s2).unwrap(); + let r1 = fill_uninit(s1).unwrap(); + let r2 = fill_uninit(s2).unwrap(); assert_eq!(r1.len(), size); assert_eq!(r2.len(), size); @@ -115,14 +115,14 @@ fn test_small_uninit() { #[test] fn test_huge() { let mut huge = [0u8; 100_000]; - getrandom(&mut huge).unwrap(); + fill(&mut huge).unwrap(); } #[test] fn test_huge_uninit() { const N: usize = 100_000; let mut huge = uninit_vec(N); - let res = getrandom_uninit(&mut huge).unwrap(); + let res = fill_uninit(&mut huge).unwrap(); assert_eq!(res.len(), N); } @@ -146,7 +146,7 @@ fn test_multithreading() { let mut v = [0u8; 1000]; for _ in 0..100 { - getrandom(&mut v).unwrap(); + fill(&mut v).unwrap(); thread::yield_now(); } }); @@ -236,7 +236,7 @@ mod custom { #[test] fn test_custom() { let mut buf = [0u8; 142]; - let res = getrandom::getrandom(&mut buf); + let res = getrandom::fill(&mut buf); assert!(res.is_err()); } }