Merge branch 'master' into zerocopy

.github/workflows/tests.yml

@@ -327,6 +327,17 @@ jobs:
       - uses: Swatinem/rust-cache@v2
       - run: cargo build -Z build-std=${{ contains(matrix.features, 'std') && 'std' || 'core'}} --target=${{ matrix.target }} --features="${{ join(matrix.features, ',') }}"
 
+  build-no-atomics:
+    name: No Atomics Build
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v3
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: riscv32i-unknown-none-elf
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo build --features custom --target riscv32i-unknown-none-elf
+
   clippy-fmt:
     name: Clippy + rustfmt
     runs-on: ubuntu-22.04

CHANGELOG.md

@@ -4,6 +4,34 @@ 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).
 
+## [0.2.12] - 2024-01-09
+### Fixed
+- Custom backend for targets without atomics [#385]
+
+### Changed
+- Improve robustness of the Hermit backend and `sys_fill_exact` [#386]
+- Raise minimum supported Apple OS versions to macOS 10.12 and iOS 10 [#388]
+
+### Added
+- Document platform support policy [#387]
+
+[#385]: https://github.com/rust-random/getrandom/pull/385
+[#386]: https://github.com/rust-random/getrandom/pull/386
+[#387]: https://github.com/rust-random/getrandom/pull/387
+[#388]: https://github.com/rust-random/getrandom/pull/388
+
+## [0.2.11] - 2023-11-08
+### Added
+- GNU/Hurd support [#370]
+
+### Changed
+- Renamed `__getrandom_internal` to `__GETRANDOM_INTERNAL`  [#369]
+- Updated link to Hermit docs [#374]
+
+[#369]: https://github.com/rust-random/getrandom/pull/369
+[#370]: https://github.com/rust-random/getrandom/pull/370
+[#374]: https://github.com/rust-random/getrandom/pull/374
+
 ## [0.2.10] - 2023-06-06
 ### Added
 - Support for PS Vita (`armv7-sony-vita-newlibeabihf`) [#359]
@@ -391,6 +419,8 @@ Publish initial implementation.
 ## [0.0.0] - 2019-01-19
 Publish an empty template library.
 
+[0.2.12]: https://github.com/rust-random/getrandom/compare/v0.2.11...v0.2.12
+[0.2.11]: https://github.com/rust-random/getrandom/compare/v0.2.10...v0.2.11
 [0.2.10]: https://github.com/rust-random/getrandom/compare/v0.2.9...v0.2.10
 [0.2.9]: https://github.com/rust-random/getrandom/compare/v0.2.8...v0.2.9
 [0.2.8]: https://github.com/rust-random/getrandom/compare/v0.2.7...v0.2.8

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "getrandom"
-version = "0.2.10" # Also update html_root_url in lib.rs when bumping this
+version = "0.2.12" # Also update html_root_url in lib.rs when bumping this
 edition = "2018"
 authors = ["The Rand Project Developers"]
 license = "MIT OR Apache-2.0"

LICENSE-MIT

@@ -1,4 +1,4 @@
-Copyright 2018 Developers of the Rand project
+Copyright (c) 2018-2024 The rust-random Project Developers
 Copyright (c) 2014 The Rust Project Developers
 
 Permission is hereby granted, free of charge, to any

README.md

@@ -3,7 +3,7 @@
 [![Build Status]][GitHub Actions] [![Crate]][crates.io] [![Documentation]][docs.rs] [![Dependency Status]][deps.rs] [![Downloads]][crates.io] [![License]][LICENSE-MIT]
 
 [GitHub Actions]: https://github.com/rust-random/getrandom/actions?query=workflow:Tests+branch:master
-[Build Status]: https://github.com/rust-random/getrandom/workflows/Tests/badge.svg?branch=master
+[Build Status]: https://github.com/rust-random/getrandom/actions/workflows/tests.yml/badge.svg?branch=master
 [crates.io]: https://crates.io/crates/getrandom
 [Crate]: https://img.shields.io/crates/v/getrandom
 [docs.rs]: https://docs.rs/getrandom
@@ -54,11 +54,28 @@ crate features, WASM support and Custom RNGs see the
 
 This crate requires Rust 1.36.0 or later.
 
-# License
+## Platform Support
+
+This crate generally supports the same operating system and platform versions that the Rust standard library does. 
+Additional targets may be supported using pluggable custom implementations.
+
+This means that as Rust drops support for old versions of operating systems (such as old Linux kernel versions, Android API levels, etc)
+in stable releases, `getrandom` may create new patch releases (`0.N.x`) that remove support for outdated platform versions.
+
+## License
 
 The `getrandom` library is distributed under either of
 
- * [Apache License, Version 2.0](LICENSE-APACHE)
- * [MIT license](LICENSE-MIT)
+ * [Apache License, Version 2.0][LICENSE-APACHE]
+ * [MIT license][LICENSE-MIT]
 
 at your option.
+
+### Contribution
+
+Unless you explicitly state otherwise, any contribution intentionally submitted
+for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
+dual licensed as above, without any additional terms or conditions.
+
+[LICENSE-APACHE]: https://github.com/rust-random/getrandom/blob/master/LICENSE-APACHE
+[LICENSE-MIT]: https://github.com/rust-random/getrandom/blob/master/LICENSE-MIT

src/3ds.rs

@@ -1,11 +1,3 @@
-// Copyright 2021 Developers of the Rand project.
-//
-// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
-// https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
-// <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
-// option. This file may not be copied, modified, or distributed
-// except according to those terms.
-
 //! Implementation for Nintendo 3DS
 use crate::util_libc::sys_fill_exact;
 use crate::Error;

src/apple-other.rs

@@ -1,24 +1,21 @@
-// Copyright 2018 Developers of the Rand project.
-//
-// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
-// https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
-// <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
-// option. This file may not be copied, modified, or distributed
-// except according to those terms.
-
-//! Implementation for iOS
+//! Implementation for iOS, tvOS, and watchOS where `getentropy` is unavailable.
 use crate::Error;
-use core::{ffi::c_void, mem::MaybeUninit, ptr::null};
+use core::{ffi::c_void, mem::MaybeUninit};
 
-#[link(name = "Security", kind = "framework")]
+// libsystem contains the libc of Darwin, and every binary ends up linked against it either way. This
+// makes it a more lightweight choice compared to `Security.framework`.
 extern "C" {
-    fn SecRandomCopyBytes(rnd: *const c_void, count: usize, bytes: *mut u8) -> i32;
+    // This RNG uses a thread-local CSPRNG to provide data, which is seeded by the operating system's root CSPRNG.
+    // Its the best option after `getentropy` on modern Darwin-based platforms that also avoids the
+    // high startup costs and linking of Security.framework.
+    //
+    // While its just an implementation detail, `Security.framework` just calls into this anyway.
+    fn CCRandomGenerateBytes(bytes: *mut c_void, size: usize) -> i32;
 }
 
 pub fn getrandom_inner(dest: &mut [MaybeUninit<u8>]) -> Result<(), Error> {
-    // Apple's documentation guarantees kSecRandomDefault is a synonym for NULL.
-    let ret = unsafe { SecRandomCopyBytes(null(), dest.len(), dest.as_mut_ptr() as *mut u8) };
-    // errSecSuccess (from SecBase.h) is always zero.
+    let ret = unsafe { CCRandomGenerateBytes(dest.as_mut_ptr() as *mut c_void, dest.len()) };
+    // kCCSuccess (from CommonCryptoError.h) is always zero.
     if ret != 0 {
         Err(Error::IOS_SEC_RANDOM)
     } else {

src/bsd_arandom.rs

@@ -1,11 +1,3 @@
-// Copyright 2018 Developers of the Rand project.
-//
-// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
-// https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
-// <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
-// option. This file may not be copied, modified, or distributed
-// except according to those terms.
-
 //! Implementation for FreeBSD and NetBSD
 use crate::{
     util_libc::{sys_fill_exact, Weak},

src/custom.rs

@@ -1,11 +1,3 @@
-// Copyright 2018 Developers of the Rand project.
-//
-// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
-// https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
-// <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
-// option. This file may not be copied, modified, or distributed
-// except according to those terms.
-
 //! An implementation which calls out to an externally defined function.
 use crate::{util::uninit_slice_fill_zero, Error};
 use core::{mem::MaybeUninit, num::NonZeroU32};

src/dragonfly.rs

@@ -1,11 +1,3 @@
-// Copyright 2021 Developers of the Rand project.
-//
-// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
-// https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
-// <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
-// option. This file may not be copied, modified, or distributed
-// except according to those terms.
-
 //! Implementation for DragonFly BSD
 use crate::{
     use_file,

src/error.rs

@@ -1,10 +1,3 @@
-// Copyright 2018 Developers of the Rand project.
-//
-// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
-// https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
-// <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
-// option. This file may not be copied, modified, or distributed
-// except according to those terms.
 use core::{fmt, num::NonZeroU32};
 
 /// A small and `no_std` compatible error type
@@ -35,7 +28,11 @@ impl Error {
     pub const UNSUPPORTED: Error = internal_error(0);
     /// The platform-specific `errno` returned a non-positive value.
     pub const ERRNO_NOT_POSITIVE: Error = internal_error(1);
-    /// Call to iOS [`SecRandomCopyBytes`](https://developer.apple.com/documentation/security/1399291-secrandomcopybytes) failed.
+    /// Encountered an unexpected situation which should not happen in practice.
+    pub const UNEXPECTED: Error = internal_error(2);
+    /// Call to [`CCRandomGenerateBytes`](https://opensource.apple.com/source/CommonCrypto/CommonCrypto-60074/include/CommonRandom.h.auto.html) failed
+    /// on iOS, tvOS, or waatchOS.
+    // TODO: Update this constant name in the next breaking release.
     pub const IOS_SEC_RANDOM: Error = internal_error(3);
     /// Call to Windows [`RtlGenRandom`](https://docs.microsoft.com/en-us/windows/win32/api/ntsecapi/nf-ntsecapi-rtlgenrandom) failed.
     pub const WINDOWS_RTL_GEN_RANDOM: Error = internal_error(4);
@@ -164,6 +161,7 @@ fn internal_desc(error: Error) -> Option<&'static str> {
     match error {
         Error::UNSUPPORTED => Some("getrandom: this target is not supported"),
         Error::ERRNO_NOT_POSITIVE => Some("errno: did not return a positive value"),
+        Error::UNEXPECTED => Some("unexpected situation"),
         Error::IOS_SEC_RANDOM => Some("SecRandomCopyBytes: iOS Security framework failure"),
         Error::WINDOWS_RTL_GEN_RANDOM => Some("RtlGenRandom: Windows system function failure"),
         Error::FAILED_RDRAND => Some("RDRAND: failed multiple times: CPU issue likely"),

src/error_impls.rs

@@ -1,10 +1,3 @@
-// Copyright 2018 Developers of the Rand project.
-//
-// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
-// https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
-// <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
-// option. This file may not be copied, modified, or distributed
-// except according to those terms.
 extern crate std;
 
 use crate::Error;

src/espidf.rs

@@ -1,11 +1,3 @@
-// Copyright 2021 Developers of the Rand project.
-//
-// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
-// https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
-// <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
-// option. This file may not be copied, modified, or distributed
-// except according to those terms.
-
 //! Implementation for ESP-IDF
 use crate::Error;
 use core::{ffi::c_void, mem::MaybeUninit};

src/fuchsia.rs

@@ -1,11 +1,3 @@
-// Copyright 2018 Developers of the Rand project.
-//
-// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
-// https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
-// <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
-// option. This file may not be copied, modified, or distributed
-// except according to those terms.
-
 //! Implementation for Fuchsia Zircon
 use crate::Error;
 use core::mem::MaybeUninit;

src/hermit.rs

@@ -1,5 +1,11 @@
+//! Implementation for Hermit
 use crate::Error;
-use core::{cmp::min, mem::MaybeUninit, num::NonZeroU32};
+use core::{mem::MaybeUninit, num::NonZeroU32};
+
+/// Minimum return value which we should get from syscalls in practice,
+/// because Hermit uses positive `i32`s for error codes:
+/// https://github.com/hermitcore/libhermit-rs/blob/main/src/errno.rs
+const MIN_RET_CODE: isize = -(i32::MAX as isize);
 
 extern "C" {
     fn sys_read_entropy(buffer: *mut u8, length: usize, flags: u32) -> isize;
@@ -8,14 +14,16 @@ extern "C" {
 pub fn getrandom_inner(mut dest: &mut [MaybeUninit<u8>]) -> Result<(), Error> {
     while !dest.is_empty() {
         let res = unsafe { sys_read_entropy(dest.as_mut_ptr() as *mut u8, dest.len(), 0) };
-        if res < 0 {
-            // SAFETY: all Hermit error codes use i32 under the hood:
-            // https://github.com/hermitcore/libhermit-rs/blob/master/src/errno.rs
-            let code = unsafe { NonZeroU32::new_unchecked((-res) as u32) };
-            return Err(code.into());
+        // Positive `isize`s can be safely casted to `usize`
+        if res > 0 && (res as usize) <= dest.len() {
+            dest = &mut dest[res as usize..];
+        } else {
+            let err = match res {
+                MIN_RET_CODE..=-1 => NonZeroU32::new(-res as u32).unwrap().into(),
+                _ => Error::UNEXPECTED,
+            };
+            return Err(err);
         }
-        let len = min(res as usize, dest.len());
-        dest = &mut dest[len..];
     }
     Ok(())
 }

src/hurd.rs

@@ -1,11 +1,3 @@
-// Copyright 2021 Developers of the Rand project.
-//
-// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
-// https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
-// <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
-// option. This file may not be copied, modified, or distributed
-// except according to those terms.
-
 //! Implementation for GNU/Hurd
 use crate::util_libc::sys_fill_exact;
 use crate::Error;

src/js.rs

@@ -1,10 +1,4 @@
-// Copyright 2018 Developers of the Rand project.
-//
-// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
-// https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
-// <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
-// option. This file may not be copied, modified, or distributed
-// except according to those terms.
+//! Implementation for WASM based on Web and Node.js
 use crate::Error;
 
 extern crate std;

src/lazy.rs

@@ -0,0 +1,56 @@
+use core::sync::atomic::{AtomicUsize, Ordering::Relaxed};
+
+// This structure represents a lazily initialized static usize value. Useful
+// when it is preferable to just rerun initialization instead of locking.
+// unsync_init will invoke an init() function until it succeeds, then return the
+// cached value for future calls.
+//
+// unsync_init supports init() "failing". If the init() method returns UNINIT,
+// that value will be returned as normal, but will not be cached.
+//
+// Users should only depend on the _value_ returned by init() functions.
+// Specifically, for the following init() function:
+//      fn init() -> usize {
+//          a();
+//          let v = b();
+//          c();
+//          v
+//      }
+// the effects of c() or writes to shared memory will not necessarily be
+// observed and additional synchronization methods may be needed.
+pub(crate) struct LazyUsize(AtomicUsize);
+
+impl LazyUsize {
+    pub const fn new() -> Self {
+        Self(AtomicUsize::new(Self::UNINIT))
+    }
+
+    // The initialization is not completed.
+    pub const UNINIT: usize = usize::max_value();
+
+    // Runs the init() function at most once, returning the value of some run of
+    // init(). Multiple callers can run their init() functions in parallel.
+    // init() should always return the same value, if it succeeds.
+    pub fn unsync_init(&self, init: impl FnOnce() -> usize) -> usize {
+        // Relaxed ordering is fine, as we only have a single atomic variable.
+        let mut val = self.0.load(Relaxed);
+        if val == Self::UNINIT {
+            val = init();
+            self.0.store(val, Relaxed);
+        }
+        val
+    }
+}
+
+// Identical to LazyUsize except with bool instead of usize.
+pub(crate) struct LazyBool(LazyUsize);
+
+impl LazyBool {
+    pub const fn new() -> Self {
+        Self(LazyUsize::new())
+    }
+
+    pub fn unsync_init(&self, init: impl FnOnce() -> bool) -> bool {
+        self.0.unsync_init(|| init() as usize) != 0
+    }
+}