Add optional support for extern_item_impls

Adds support for the nightly-only feature `extern_item_impls` gated behind a new fRust flag `getrandom_extern_item_impls`. This allows overriding the default backend implementation or providing one where it would otherwise not be available from safe Rust code in a user-friendly and idiomatic way.

Offering this PR largely as a hypothetical since there are open questions (e.g., if this was stable, should it be optional or default? should there be a way to prevent overriding the default backend to guard against malicious libraries?, etc.)

Author: bushrat011899

Cargo.toml

@@ -94,6 +94,7 @@ wasm-bindgen-test = "0.3"
 [lints.rust.unexpected_cfgs]
 level = "warn"
 check-cfg = [
+  'cfg(getrandom_extern_item_impls)',
   'cfg(getrandom_backend, values("custom", "efi_rng", "rdrand", "rndr", "linux_getrandom", "linux_raw", "windows_legacy", "unsupported"))',
   'cfg(getrandom_msan)',
   'cfg(getrandom_test_linux_fallback)',

README.md

@@ -201,6 +201,32 @@ unsafe extern "Rust" fn __getrandom_v03_custom(
 }
 ```
 
+### Externally Implemented Interface (Nightly)
+
+Using the nightly-only feature [`extern_item_impls`](https://github.com/rust-lang/rust/issues/125418)
+it is possible to provide a custom backend for `getrandom`, even to override
+an existing first-party implementation. First, enable the `getrandom_extern_item_impls`
+Rust flag to allow usage of this nightly feature. Then, you may provide
+implementations for `fill_uninit`, `u32`, and/or u64` with an attribute macro
+from the `implemtation` module.
+
+```rust
+use core::mem::MaybeUninit;
+
+#[getrandom::implementation::fill_uninit]
+fn my_fill_uninit_implementation(
+    dest: &mut [MaybeUninit<u8>]
+) -> Result<(), getrandom::Error> {
+    // ...
+    Ok(())
+}
+```
+
+If `getrandom` is able to provide a backend implemtation, it will be a weak
+symbol that can be overridden as above. If no implementation is available,
+a compilation error will be raised with instructions for how to provide
+an implementation.
+
 ### Unsupported backend
 
 In some rare scenarios, you might be compiling this crate for an unsupported

src/backends.rs

@@ -7,53 +7,88 @@
 //! The function MUST NOT ever write uninitialized bytes into `dest`,
 //! regardless of what value it returns.
 
+/// Declares this function as an external implementation of [`u32`](crate::u32).
+#[cfg_attr(getrandom_extern_item_impls, eii(u32))]
+pub(crate) fn inner_u32() -> Result<u32, crate::Error> {
+    default_u32()
+}
+
+/// Declares this function as an external implementation of [`u64`](crate::u64).
+#[cfg_attr(getrandom_extern_item_impls, eii(u64))]
+pub(crate) fn inner_u64() -> Result<u64, crate::Error> {
+    default_u64()
+}
+
+macro_rules! implementation {
+    () => {
+        use $crate::util::{inner_u32 as default_u32, inner_u64 as default_u64};
+        
+        /// Declares this function as an external implementation of [`fill_uninit`](crate::fill_uninit).
+        #[cfg_attr(getrandom_extern_item_impls, eii(fill_uninit))]
+        pub(crate) fn fill_inner(
+            dest: &mut [::core::mem::MaybeUninit<u8>],
+        ) -> Result<(), $crate::Error>;
+    };
+    ($backend:ident) => {
+        use $backend::{inner_u32 as default_u32, inner_u64 as default_u64};
+        
+        /// Declares this function as an external implementation of [`fill_uninit`](crate::fill_uninit).
+        #[cfg_attr(getrandom_extern_item_impls, eii(fill_uninit))]
+        pub(crate) fn fill_inner(
+            dest: &mut [::core::mem::MaybeUninit<u8>],
+        ) -> Result<(), $crate::Error> {
+            $backend::fill_inner(dest)
+        }
+    };
+}
+
 cfg_if! {
     if #[cfg(getrandom_backend = "custom")] {
         mod custom;
-        pub use custom::*;
+        implementation!(custom);
     } else if #[cfg(getrandom_backend = "linux_getrandom")] {
         mod getrandom;
-        pub use getrandom::*;
+        implementation!(getrandom);
     } else if #[cfg(getrandom_backend = "linux_raw")] {
         mod linux_raw;
-        pub use linux_raw::*;
+        implementation!(linux_raw);
     } else if #[cfg(getrandom_backend = "rdrand")] {
         mod rdrand;
-        pub use rdrand::*;
+        implementation!(rdrand);
     } else if #[cfg(getrandom_backend = "rndr")] {
         mod rndr;
-        pub use rndr::*;
+        implementation!(rndr);
     } else if #[cfg(getrandom_backend = "efi_rng")] {
         mod efi_rng;
-        pub use efi_rng::*;
+        implementation!(efi_rng);
     } else if #[cfg(getrandom_backend = "windows_legacy")] {
         mod windows_legacy;
-        pub use windows_legacy::*;
+        implementation!(windows_legacy);
     } else if #[cfg(getrandom_backend = "unsupported")] {
         mod unsupported;
-        pub use unsupported::*;
+        implementation!(unsupported);
     } else if #[cfg(all(target_os = "linux", target_env = ""))] {
         mod linux_raw;
-        pub use linux_raw::*;
+        implementation!(linux_raw);
     } else if #[cfg(target_os = "espidf")] {
         mod esp_idf;
-        pub use esp_idf::*;
+        implementation!(esp_idf);
     } else if #[cfg(any(
         target_os = "haiku",
         target_os = "redox",
         target_os = "nto",
         target_os = "aix",
     ))] {
         mod use_file;
-        pub use use_file::*;
+        implementation!(use_file);
     } else if #[cfg(any(
         target_os = "macos",
         target_os = "openbsd",
         target_os = "vita",
         target_os = "emscripten",
     ))] {
         mod getentropy;
-        pub use getentropy::*;
+        implementation!(getentropy);
     } else if #[cfg(any(
         // Rust supports Android API level 19 (KitKat) [0] and the next upgrade targets
         // level 21 (Lollipop) [1], while `getrandom(2)` was added only in
@@ -101,7 +136,7 @@ cfg_if! {
     ))] {
         mod use_file;
         mod linux_android_with_fallback;
-        pub use linux_android_with_fallback::*;
+        implementation!(linux_android_with_fallback);
     } else if #[cfg(any(
         target_os = "android",
         target_os = "linux",
@@ -115,57 +150,59 @@ cfg_if! {
         all(target_os = "horizon", target_arch = "arm"),
     ))] {
         mod getrandom;
-        pub use getrandom::*;
+        implementation!(getrandom);
     } else if #[cfg(target_os = "solaris")] {
         mod solaris;
-        pub use solaris::*;
+        implementation!(solaris);
     } else if #[cfg(target_os = "netbsd")] {
         mod netbsd;
-        pub use netbsd::*;
+        implementation!(netbsd);
     } else if #[cfg(target_os = "fuchsia")] {
         mod fuchsia;
-        pub use fuchsia::*;
+        implementation!(fuchsia);
     } else if #[cfg(any(
         target_os = "ios",
         target_os = "visionos",
         target_os = "watchos",
         target_os = "tvos",
     ))] {
         mod apple_other;
-        pub use apple_other::*;
+        implementation!(apple_other);
     } else if #[cfg(all(target_arch = "wasm32", target_os = "wasi"))] {
         cfg_if! {
             if #[cfg(target_env = "p1")] {
                 mod wasi_p1;
-                pub use wasi_p1::*;
+                implementation!(wasi_p1);
             } else {
                 mod wasi_p2_3;
-                pub use wasi_p2_3::*;
+                implementation!(wasi_p2_3);
             }
         }
     } else if #[cfg(target_os = "hermit")] {
         mod hermit;
-        pub use hermit::*;
+        implementation!(hermit);
     } else if #[cfg(target_os = "vxworks")] {
         mod vxworks;
-        pub use vxworks::*;
+        implementation!(vxworks);
     } else if #[cfg(target_os = "solid_asp3")] {
         mod solid;
-        pub use solid::*;
+        implementation!(solid);
     } else if #[cfg(all(windows, target_vendor = "win7"))] {
         mod windows_legacy;
-        pub use windows_legacy::*;
+        implementation!(windows_legacy);
     } else if #[cfg(windows)] {
         mod windows;
-        pub use windows::*;
+        implementation!(windows);
     } else if #[cfg(all(target_arch = "x86_64", target_env = "sgx"))] {
         mod rdrand;
-        pub use rdrand::*;
+        implementation!(rdrand);
     } else if #[cfg(all(target_arch = "wasm32", any(target_os = "unknown", target_os = "none")))] {
         cfg_if! {
             if #[cfg(feature = "wasm_js")] {
                 mod wasm_js;
-                pub use wasm_js::*;
+                implementation!(wasm_js);
+            } else if #[cfg(getrandom_extern_item_impls)] {
+                implementation!();
             } else {
                 compile_error!(concat!(
                     "The wasm32-unknown-unknown targets are not supported by default; \
@@ -175,6 +212,8 @@ cfg_if! {
                 ));
             }
         }
+    } else if #[cfg(getrandom_extern_item_impls)] {
+        implementation!();
     } else {
         compile_error!(concat!(
             "target is not supported. You may need to define a custom backend see: \

src/lib.rs

@@ -26,6 +26,7 @@
     clippy::unnecessary_cast,
     clippy::useless_conversion
 )]
+#![cfg_attr(getrandom_extern_item_impls, feature(extern_item_impls))]
 
 #[macro_use]
 extern crate cfg_if;
@@ -50,6 +51,32 @@ pub use sys_rng::SysRng;
 
 pub use crate::error::{Error, RawOsError};
 
+#[cfg(getrandom_extern_item_impls)]
+pub mod implementation {
+    //! Provides Externally Implementable Iterfaces for the core functionality of this crate.
+    //! This allows `getrandom` to provide a default implementation and a common interface
+    //! for all crates to use, while giving users a safe way to override that default where required.
+    //!
+    //! Must be enabled via the `getrandom_extern_item_impls` compiler flag, as this functionality
+    //! is currently limited to nightly.
+    //!
+    //! # Examples
+    //!
+    //! ```rust
+    //! # use core::mem::MaybeUninit;
+    //! #[getrandom::implementation::fill_uninit]
+    //! fn my_fill_uninit_implementation(
+    //!     dest: &mut [MaybeUninit<u8>]
+    //! ) -> Result<(), getrandom::Error> {
+    //!     // ...
+    //! #   let _ = dest;
+    //! #   Err(Error::UNSUPPORTED)
+    //! }
+    //! ```
+
+    pub use crate::backends::{fill_uninit, u32, u64};
+}
+
 /// 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