Minor updates (#12)

Author: newpavlov

Cargo.toml

@@ -3,7 +3,11 @@ name = "getrandom"
 version = "0.1.0"
 authors = ["The Rand Project Developers"]
 license = "MIT OR Apache-2.0"
-description = "A small cross-platform library to securely get random data (entropy)"
+description = "A small cross-platform library for retrieving random data from system source"
+documentation = "https://docs.rs/getrandom"
+repository = "https://github.com/rust-random/getrandom"
+categories = ["os", "no-std"]
+exclude = ["utils/*", ".*", "appveyor.yml"]
 
 [badges]
 travis-ci = { repository = "rust-random/getrandom" }
@@ -18,8 +22,7 @@ members = [
 log = { version = "0.4", optional = true }
 
 [target.'cfg(unix)'.dependencies]
-# In general, we need at least 0.2.27. On Solaris, we need some unknown newer version.
-libc = "0.2.50"
+libc = "0.2.29"
 
 [target.'cfg(windows)'.dependencies]
 winapi = { version = "0.3.6", features = ["minwindef", "ntsecapi", "winnt"] }

README.md

@@ -1,16 +1,20 @@
-# Rand
+# getrandom
 
 [![Build Status](https://travis-ci.org/rust-random/getrandom.svg?branch=master)](https://travis-ci.org/rust-random/getrandom)
 [![Build Status](https://ci.appveyor.com/api/projects/status/github/rust-random/getrandom?svg=true)](https://ci.appveyor.com/project/rust-random/getrandom)
 [![Crate](https://img.shields.io/crates/v/getrandom.svg)](https://crates.io/crates/getrandom)
-[![API](https://docs.rs/getrandom/badge.svg)](https://docs.rs/getrandom)
+[![Documentation](https://docs.rs/getrandom/badge.svg)](https://docs.rs/getrandom)
+[![Dependency status](https://deps.rs/repo/github/rust-random/getrandom/status.svg)](https://deps.rs/repo/github/rust-random/getrandom)
 
-A Rust library to securely get random entropy. This crate derives its name from
-Linux's `getrandom` function, but is cross platform, roughly supporting the same
-set of platforms as Rust's `std` lib.
 
-This is a low-level API. Most users should prefer a high-level random-number
-library like [Rand] or a cryptography library.
+A Rust library for retrieving random data from (operating) system source. It is
+assumed that system always provides high-quality cryptographically secure random
+data, ideally backed by hardware entropy sources. This crate derives its name
+from Linux's `getrandom` function, but is cross platform, roughly supporting
+the same set of platforms as Rust's `std` lib.
+
+This is a low-level API. Most users should prefer using high-level random-number
+library like [`rand`].
 
 [Rand]: https://crates.io/crates/rand
 
@@ -36,7 +40,7 @@ fn get_random_buf() -> Result<[u8; 32], getrandom::Error> {
 
 ## Features
 
-This library is `no_std` compatible on SGX but requires `std` on most platforms.
+This library is `no_std` compatible, but uses `std` on most platforms.
 
 The `log` library is supported as an optional dependency. If enabled, error
 reporting will be improved on some platforms.
@@ -47,15 +51,17 @@ one of the following features must be enabled:
 -   [`wasm-bindgen`](https://crates.io/crates/wasm_bindgen)
 -   [`stdweb`](https://crates.io/crates/stdweb)
 
-## Versions
+## Minimum Supported Rust Version
 
 This crate requires Rustc version 1.28.0 or later due to usage of `NonZeroU32`.
 
 
 # License
 
-The `getrandom` library is distributed under the terms of both the MIT license
-and the Apache License (Version 2.0).
+The `getrandom` library is distributed under either of
+
+ * [Apache License, Version 2.0](LICENSE-APACHE)
+ * [MIT license](LICENSE-MIT)
+
+at your option.
 
-See [LICENSE-APACHE](LICENSE-APACHE) and [LICENSE-MIT](LICENSE-MIT), and
-[COPYRIGHT](COPYRIGHT) for details.

src/dummy.rs

@@ -7,13 +7,13 @@
 // except according to those terms.
 
 //! A dummy implementation for unsupported targets which always returns
-//! `Err(ERROR_UNAVAILABLE)`
+//! `Err(Error::UNAVAILABLE)`
 use std::num::NonZeroU32;
-use {Error, ERROR_UNAVAILABLE};
+use Error;
 
 pub fn getrandom_inner(_: &mut [u8]) -> Result<(), Error> {
     error!("no support for this platform");
-    Err(ERROR_UNAVAILABLE)
+    Err(Error::UNAVAILABLE)
 }
 
 #[inline(always)]

src/error.rs

@@ -12,49 +12,45 @@ use core::fmt;
 #[cfg(not(target_env = "sgx"))]
 use std::{io, error};
 
-// A randomly-chosen 16-bit prefix for our codes
-pub(crate) const CODE_PREFIX: u32 = 0x57f40000;
-const CODE_UNKNOWN: u32 = CODE_PREFIX | 0;
-const CODE_UNAVAILABLE: u32 = CODE_PREFIX | 1;
-
-/// An unknown error.
-/// 
-/// This is the following constant: 57F40000 (hex) / 1475608576 (decimal).
-pub const ERROR_UNKNOWN: Error = Error(unsafe {
-    NonZeroU32::new_unchecked(CODE_UNKNOWN)
-});
-
-/// No generator is available.
-/// 
-/// This is the following constant: 57F40001 (hex) / 1475608577 (decimal).
-pub const ERROR_UNAVAILABLE: Error = Error(unsafe {
-    NonZeroU32::new_unchecked(CODE_UNAVAILABLE)
-});
+// A randomly-chosen 24-bit prefix for our codes
+pub(crate) const CODE_PREFIX: u32 = 0x57f4c500;
+const CODE_UNKNOWN: u32 = CODE_PREFIX | 0x00;
+const CODE_UNAVAILABLE: u32 = CODE_PREFIX | 0x01;
 
 /// The error type.
-/// 
+///
 /// This type is small and no-std compatible.
 #[derive(Copy, Clone, Eq, PartialEq)]
 pub struct Error(NonZeroU32);
 
 impl Error {
+    /// An unknown error.
+    pub const UNKNOWN: Error = Error(unsafe {
+        NonZeroU32::new_unchecked(CODE_UNKNOWN)
+    });
+
+    /// No generator is available.
+    pub const UNAVAILABLE: Error = Error(unsafe {
+        NonZeroU32::new_unchecked(CODE_UNAVAILABLE)
+    });
+
     /// Extract the error code.
-    /// 
+    ///
     /// This may equal one of the codes defined in this library or may be a
     /// system error code.
-    /// 
+    ///
     /// One may attempt to format this error via the `Display` implementation.
     pub fn code(&self) -> NonZeroU32 {
         self.0
     }
-    
+
     fn msg(&self) -> Option<&'static str> {
         if let Some(msg) = super::error_msg_inner(self.0) {
             Some(msg)
         } else {
             match *self {
-                ERROR_UNKNOWN => Some("getrandom: unknown error"),
-                ERROR_UNAVAILABLE => Some("getrandom: unavailable"),
+                Error::UNKNOWN => Some("getrandom: unknown error"),
+                Error::UNAVAILABLE => Some("getrandom: unavailable"),
                 _ => None
             }
         }
@@ -92,7 +88,7 @@ impl From<io::Error> for Error {
             .and_then(|code| NonZeroU32::new(code as u32))
             .map(|code| Error(code))
             // in practice this should never happen
-            .unwrap_or(ERROR_UNKNOWN)
+            .unwrap_or(Error::UNKNOWN)
     }
 }
 
@@ -113,7 +109,7 @@ impl error::Error for Error { }
 mod tests {
     use std::mem::size_of;
     use super::Error;
-    
+
     #[test]
     fn test_size() {
         assert_eq!(size_of::<Error>(), 4);

src/lib.rs

@@ -67,12 +67,30 @@
 //! # Error handling
 //!
 //! We always choose failure over returning insecure "random" bytes. In general,
-//! on supported platforms, failure is unlikely, though not impossible. If an
-//! error does occur, then it is likely that it will occur on every call to
+//! on supported platforms, failure is highly unlikely, though not impossible.
+//! If an error does occur, then it is likely that it will occur on every call to
 //! `getrandom`, hence after the first successful call one can be reasonably
 //! confident that no errors will occur.
-//! 
-//! On unsupported platforms, `getrandom` always fails.
+//!
+//! On unsupported platforms, `getrandom` always fails with [`Error::UNAVAILABLE`].
+//!
+//! ## Error codes
+//! The crate uses the following custom error codes:
+//! - `0x57f4c500` (dec: 1475659008) - an unknown error. Constant:
+//! [`Error::UNKNOWN`]
+//! - `0x57f4c501` (dec: 1475659009) - no generator is available. Constant:
+//! [`Error::UNAVAILABLE`]
+//! - `0x57f4c580` (dec: 1475659136) - `self.crypto` is undefined,
+//! `wasm-bindgen` specific error.
+//! - `0x57f4c581` (dec: 1475659137) - `crypto.getRandomValues` is undefined,
+//! `wasm-bindgen` specific error.
+//!
+//! These codes are provided for reference only and should not be matched upon
+//! (but you can match on `Error` constants). The codes may change in future and
+//! such change will not be considered a breaking one.
+//!
+//! Other error codes will originate from an underlying system. In case if such
+//! error is encountered, please consult with your system documentation.
 //!
 //! [1]: http://man7.org/linux/man-pages/man2/getrandom.2.html
 //! [2]: http://man7.org/linux/man-pages/man4/urandom.4.html
@@ -128,10 +146,10 @@ extern crate wasm_bindgen;
 ))]
 mod utils;
 mod error;
-pub use error::{Error, ERROR_UNKNOWN, ERROR_UNAVAILABLE};
+pub use error::Error;
 
 // System-specific implementations.
-// 
+//
 // These should all provide getrandom_inner with the same signature as getrandom.
 
 macro_rules! mod_use {
@@ -215,12 +233,12 @@ mod_use!(
 
 /// 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.
-/// 
+///
 /// Blocking is possible, at least during early boot; see module documentation.
-/// 
+///
 /// 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).

src/sgx.rs

@@ -7,7 +7,7 @@
 // except according to those terms.
 
 //! Implementation for SGX using RDRAND instruction
-use {Error, ERROR_UNKNOWN};
+use Error;
 
 use core::{mem, ptr};
 use core::arch::x86_64::_rdrand64_step;
@@ -27,7 +27,7 @@ fn get_rand_u64() -> Result<u64, Error> {
             }
         };
     }
-    Err(ERROR_UNKNOWN)
+    Err(Error::UNKNOWN)
 }
 
 pub fn getrandom_inner(mut dest: &mut [u8]) -> Result<(), Error> {

src/wasm32_bindgen.rs

@@ -16,11 +16,11 @@ use wasm_bindgen::prelude::*;
 
 use __wbg_shims::*;
 use Error;
+use error::CODE_PREFIX;
 use utils::use_init;
 
-const CODE_PREFIX: u32 = ::error::CODE_PREFIX | 0x8e00;
-const CODE_CRYPTO_UNDEF: u32 = CODE_PREFIX | 1;
-const CODE_GRV_UNDEF: u32 = CODE_PREFIX | 2;
+const CODE_CRYPTO_UNDEF: u32 = CODE_PREFIX | 0x80;
+const CODE_GRV_UNDEF: u32 = CODE_PREFIX | 0x81;
 
 #[derive(Clone, Debug)]
 pub enum RngSource {

src/wasm32_stdweb.rs

@@ -15,7 +15,7 @@ use std::num::NonZeroU32;
 use stdweb::unstable::TryInto;
 use stdweb::web::error::Error as WebError;
 
-use {Error, ERROR_UNAVAILABLE, ERROR_UNKNOWN};
+use Error;
 use utils::use_init;
 
 #[derive(Clone, Debug)]
@@ -67,7 +67,7 @@ fn getrandom_init() -> Result<RngSource, Error> {
     } else {
         let err: WebError = js!{ return @{ result }.error }.try_into().unwrap();
         error!("getrandom unavailable: {}", err);
-        Err(ERROR_UNAVAILABLE)
+        Err(Error::UNAVAILABLE)
     }
 }
 
@@ -103,7 +103,7 @@ fn getrandom_fill(source: &mut RngSource, dest: &mut [u8]) -> Result<(), Error>
         if js!{ return @{ result.as_ref() }.success } != true {
             let err: WebError = js!{ return @{ result }.error }.try_into().unwrap();
             error!("getrandom failed: {}", err);
-            return Err(ERROR_UNKNOWN)
+            return Err(Error::UNKNOWN)
         }
     }
     Ok(())