Merge branch 'master' into doc-bn

4 files changed, 108 insertions, 0 deletions

diff --git a/openssl/src/ec_key.rs b/openssl/src/ec_key.rs
index cb7c4996..f983aaf7 100644
--- a/openssl/src/ec_key.rs
+++ b/openssl/src/ec_key.rs
@@ -1,3 +1,4 @@
+#![doc(hidden)]
 #![deprecated(since = "0.9.2", note = "renamed to `ec`")]
 
 pub use ec::{EcKey, EcKeyRef};
diff --git a/openssl/src/memcmp.rs b/openssl/src/memcmp.rs
index 0ca12c86..3b831e6f 100644
--- a/openssl/src/memcmp.rs
+++ b/openssl/src/memcmp.rs
@@ -1,3 +1,34 @@
+//! Utilities to safely compare cryptographic values.
+//!
+//! Extra care must be taken when comparing values in
+//! cryptographic code. If done incorrectly, it can lead
+//! to a [timing attack](https://en.wikipedia.org/wiki/Timing_attack).
+//! By analyzing the time taken to execute parts of a cryptographic
+//! algorithm, and attacker can attempt to compromise the
+//! cryptosystem.
+//!
+//! The utilities in this module are designed to be resistant
+//! to this type of attack.
+//!
+//! # Examples
+//!
+//! To perform a constant-time comparision of two arrays of the same length but different
+//! values:
+//!
+//! ```
+//! use openssl::memcmp::eq;
+//!
+//! // We want to compare `a` to `b` and `c`, without giving
+//! // away through timing analysis that `c` is more similar to `a`
+//! // than `b`.
+//! let a = [0, 0, 0];
+//! let b = [1, 1, 1];
+//! let c = [0, 0, 1];
+//!
+//! // These statements will execute in the same amount of time.
+//! assert!(!eq(&a, &b));
+//! assert!(!eq(&a, &c));
+//! ```
 use libc::size_t;
 use ffi;
 
@@ -10,6 +41,26 @@ use ffi;
 ///
 /// This function will panic the current task if `a` and `b` do not have the same
 /// length.
+///
+/// # Examples
+///
+/// To perform a constant-time comparision of two arrays of the same length but different
+/// values:
+///
+/// ```
+/// use openssl::memcmp::eq;
+///
+/// // We want to compare `a` to `b` and `c`, without giving
+/// // away through timing analysis that `c` is more similar to `a`
+/// // than `b`.
+/// let a = [0, 0, 0];
+/// let b = [1, 1, 1];
+/// let c = [0, 0, 1];
+///
+/// // These statements will execute in the same amount of time.
+/// assert!(!eq(&a, &b));
+/// assert!(!eq(&a, &c));
+/// ```
 pub fn eq(a: &[u8], b: &[u8]) -> bool {
     assert!(a.len() == b.len());
     let ret = unsafe {
diff --git a/openssl/src/nid.rs b/openssl/src/nid.rs
index afbd60a5..df1090c1 100644
--- a/openssl/src/nid.rs
+++ b/openssl/src/nid.rs
@@ -1,15 +1,43 @@
+//! A collection of numerical identifiers for OpenSSL objects.
 use ffi;
 use libc::c_int;
 
+/// A numerical identifier for an OpenSSL object.
+///
+/// Objects in OpenSSL can have a short name, a long name, and
+/// a numerical identifier (NID). For convenience, objects
+/// are usually represented in source code using these numeric
+/// identifiers.
+///
+/// Users should generally not need to create new `Nid`s.
+///
+/// # Examples
+///
+/// To view the integer representation of a `Nid`:
+///
+/// ```
+/// use openssl::nid;
+///
+/// assert!(nid::AES_256_GCM.as_raw() == 901);
+/// ```
+///
+/// # External Documentation
+///
+/// The following documentation provides context about `Nid`s and their usage
+/// in OpenSSL.
+///
+/// - [Obj_nid2obj](https://www.openssl.org/docs/man1.1.0/crypto/OBJ_create.html)
 #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
 pub struct Nid(c_int);
 
 #[allow(non_snake_case)]
 impl Nid {
+    /// Create a `Nid` from an integer representation.
     pub fn from_raw(raw: c_int) -> Nid {
         Nid(raw)
     }
 
+    /// Return the integer representation of a `Nid`.
     pub fn as_raw(&self) -> c_int {
         self.0
     }
diff --git a/openssl/src/rand.rs b/openssl/src/rand.rs
index c1c49e7b..da52ef5f 100644
--- a/openssl/src/rand.rs
+++ b/openssl/src/rand.rs
@@ -1,9 +1,37 @@
+//! Utilities for secure random number generation.
+//!
+//! # Examples
+//!
+//! To generate a buffer with cryptographically strong bytes:
+//!
+//! ```
+//! use openssl::rand::rand_bytes;
+//!
+//! let mut buf = [0; 256];
+//! rand_bytes(&mut buf).unwrap();
+//! ```
 use libc::c_int;
 use ffi;
 
 use cvt;
 use error::ErrorStack;
 
+/// Fill buffer with cryptographically strong pseudo-random bytes.
+///
+/// # Examples
+///
+/// To generate a buffer with cryptographically strong bytes:
+///
+/// ```
+/// use openssl::rand::rand_bytes;
+///
+/// let mut buf = [0; 256];
+/// rand_bytes(&mut buf).unwrap();
+/// ```
+///
+/// # External OpenSSL Documentation
+///
+/// [RAND_bytes](https://www.openssl.org/docs/man1.1.0/crypto/RAND_bytes.html)
 pub fn rand_bytes(buf: &mut [u8]) -> Result<(), ErrorStack> {
     unsafe {
         ffi::init();