Rename getrandom_os → getrandom_inner; more WASM doc

Author: dhardy

README.md

@@ -34,6 +34,16 @@ fn get_random_buf() -> Result<[u8; 32], getrandom::Error> {
 }
 ```
 
+## Features
+
+This library is `no_std` compatible on SGX but requires `std` on most platforms.
+
+For WebAssembly (`wasm32`), Enscripten targets are supported directly; otherwise
+one of the following features must be enabled:
+
+-   [`wasm-bindgen`](https://crates.io/crates/wasm_bindgen)
+-   [`stdweb`](https://crates.io/crates/stdweb)
+
 
 # License
 

src/cloudabi.rs

@@ -11,7 +11,7 @@ extern "C" {
     fn cloudabi_sys_random_get(buf: *mut u8, len: usize) -> u16;
 }
 
-pub fn getrandom_os(dest: &mut [u8]) -> Result<(), Error> {
+pub fn getrandom_inner(dest: &mut [u8]) -> Result<(), Error> {
     let errno = unsafe { cloudabi_sys_random_get(dest.as_ptr(), dest.len()) };
     if errno == 0 {
         Ok(())

src/dragonfly_haiku.rs

@@ -15,7 +15,7 @@ use std::cell::RefCell;
 
 thread_local!(static RNG_FILE: RefCell<Option<File>> = RefCell::new(None));
 
-pub fn getrandom_os(dest: &mut [u8]) -> Result<(), Error> {
+pub fn getrandom_inner(dest: &mut [u8]) -> Result<(), Error> {
     RNG_FILE.with(|f| {
         use_init(f,
             || File::open("/dev/random").map_err(From::from),

src/dummy.rs

@@ -10,6 +10,6 @@
 //! `Err(UNAVAILABLE_ERROR)`
 use super::UNAVAILABLE_ERROR;
 
-pub fn getrandom_os(dest: &mut [u8]) -> Result<(), Error> {
+pub fn getrandom_inner(dest: &mut [u8]) -> Result<(), Error> {
     Err(UNAVAILABLE_ERROR)
 }

src/emscripten.rs

@@ -15,7 +15,7 @@ use super::utils::use_init;
 
 thread_local!(static RNG_FILE: RefCell<Option<File>> = RefCell::new(None));
 
-pub fn getrandom_os(dest: &mut [u8]) -> Result<(), Error> {
+pub fn getrandom_inner(dest: &mut [u8]) -> Result<(), Error> {
     // `Crypto.getRandomValues` documents `dest` should be at most 65536
     // bytes. `crypto.randomBytes` documents: "To minimize threadpool
     // task length variation, partition large randomBytes requests when

src/freebsd.rs

@@ -13,7 +13,7 @@ use super::Error;
 use core::ptr;
 use std::io;
 
-pub fn getrandom_os(dest: &mut [u8]) -> Result<(), Error> {
+pub fn getrandom_inner(dest: &mut [u8]) -> Result<(), Error> {
     let mib = [libc::CTL_KERN, libc::KERN_ARND];
     // kern.arandom permits a maximum buffer size of 256 bytes
     for chunk in dest.chunks_mut(256) {

src/fuchsia.rs

@@ -11,7 +11,7 @@ extern crate fuchsia_cprng;
 
 use super::Error;
 
-pub fn getrandom_os(dest: &mut [u8]) -> Result<(), Error> {
+pub fn getrandom_inner(dest: &mut [u8]) -> Result<(), Error> {
     fuchsia_cprng::cprng_draw(dest);
     Ok(())
 }

src/lib.rs

@@ -42,7 +42,8 @@
 //! The bare WASM target `wasm32-unknown-unknown` tries to call the javascript
 //! methods directly, using either `stdweb` or `wasm-bindgen` depending on what
 //! features are activated for this crate. Note that if both features are
-//! enabled `wasm-bindgen` will be used.
+//! enabled `wasm-bindgen` will be used. If neither feature is enabled,
+//! `getrandom` will always fail.
 //!
 //! ## Early boot
 //!
@@ -112,14 +113,14 @@ pub use error::{Error, UNKNOWN_ERROR, UNAVAILABLE_ERROR};
 
 // System-specific implementations.
 // 
-// These should all provide getrandom_os with the same signature as getrandom.
+// These should all provide getrandom_inner with the same signature as getrandom.
 
 macro_rules! mod_use {
     ($cond:meta, $module:ident) => {
         #[$cond]
         mod $module;
         #[$cond]
-        use $module::getrandom_os;
+        use $module::getrandom_inner;
     }
 }
 
@@ -204,5 +205,5 @@ mod_use!(
 /// significantly slower than a user-space CSPRNG; for the latter consider
 /// [`rand::thread_rng`](https://docs.rs/rand/*/rand/fn.thread_rng.html).
 pub fn getrandom(dest: &mut [u8]) -> Result<(), Error> {
-    getrandom_os(dest)
+    getrandom_inner(dest)
 }

src/linux_android.rs

@@ -38,7 +38,7 @@ fn syscall_getrandom(dest: &mut [u8]) -> Result<(), io::Error> {
     Ok(())
 }
 
-pub fn getrandom_os(dest: &mut [u8]) -> Result<(), Error> {
+pub fn getrandom_inner(dest: &mut [u8]) -> Result<(), Error> {
     RNG_SOURCE.with(|f| {
         use_init(f,
         || {

src/macos.rs

@@ -21,7 +21,7 @@ extern {
     ) -> c_int;
 }
 
-pub fn getrandom_os(dest: &mut [u8]) -> Result<(), Error> {
+pub fn getrandom_inner(dest: &mut [u8]) -> Result<(), Error> {
     let ret = unsafe {
         SecRandomCopyBytes(
             kSecRandomDefault,