From 0f0ab2e4255983d03dfc452c3dceba85877baa68 Mon Sep 17 00:00:00 2001 From: johnthagen Date: Thu, 28 Sep 2017 09:28:08 -0400 Subject: [PATCH 1/7] Hide ec_key module in docs because it is deprecated --- openssl/src/ec_key.rs | 1 + 1 file changed, 1 insertion(+) 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}; From 220c707fd95de3f3230365a8ee9dd8789a1ee421 Mon Sep 17 00:00:00 2001 From: johnthagen Date: Thu, 28 Sep 2017 09:49:03 -0400 Subject: [PATCH 2/7] Document rand module --- openssl/src/rand.rs | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/openssl/src/rand.rs b/openssl/src/rand.rs index c1c49e7b..9fe22226 100644 --- a/openssl/src/rand.rs +++ b/openssl/src/rand.rs @@ -1,9 +1,27 @@ +//! Cryptographically strong random bytes. +//! +//! This module exposes functionality to put cryptographically strong +//! pseudo-random bytes into a buffer. +//! +//! # Examples +//! +//! To generate a buffer with cryptographically strong bytes: +//! +//! ``` +//! let muf 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) use libc::c_int; use ffi; use cvt; use error::ErrorStack; +/// Fills buffer with cryptographically strong pseudo-random bytes. pub fn rand_bytes(buf: &mut [u8]) -> Result<(), ErrorStack> { unsafe { ffi::init(); From 26fa22fe04def3322214a7fad18589dc1858e350 Mon Sep 17 00:00:00 2001 From: johnthagen Date: Thu, 28 Sep 2017 09:52:46 -0400 Subject: [PATCH 3/7] Fix typos --- openssl/src/rand.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/openssl/src/rand.rs b/openssl/src/rand.rs index 9fe22226..cd700ff1 100644 --- a/openssl/src/rand.rs +++ b/openssl/src/rand.rs @@ -8,7 +8,7 @@ //! To generate a buffer with cryptographically strong bytes: //! //! ``` -//! let muf buf = [0; 256] +//! let muf buf = [0; 256]; //! rand_bytes(&mut buf).unwrap(); //! ``` //! @@ -21,7 +21,7 @@ use ffi; use cvt; use error::ErrorStack; -/// Fills buffer with cryptographically strong pseudo-random bytes. +/// Fill buffer with cryptographically strong pseudo-random bytes. pub fn rand_bytes(buf: &mut [u8]) -> Result<(), ErrorStack> { unsafe { ffi::init(); From c4b044b6ba18f8703adcec3e2ee5a5155f75e979 Mon Sep 17 00:00:00 2001 From: johnthagen Date: Thu, 28 Sep 2017 10:36:53 -0400 Subject: [PATCH 4/7] Fix doc test and move external documentation link to rand_bytes function --- openssl/src/rand.rs | 28 +++++++++++++++++++--------- 1 file changed, 19 insertions(+), 9 deletions(-) diff --git a/openssl/src/rand.rs b/openssl/src/rand.rs index cd700ff1..da52ef5f 100644 --- a/openssl/src/rand.rs +++ b/openssl/src/rand.rs @@ -1,20 +1,15 @@ -//! Cryptographically strong random bytes. -//! -//! This module exposes functionality to put cryptographically strong -//! pseudo-random bytes into a buffer. +//! Utilities for secure random number generation. //! //! # Examples //! //! To generate a buffer with cryptographically strong bytes: //! //! ``` -//! let muf buf = [0; 256]; +//! 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) use libc::c_int; use ffi; @@ -22,6 +17,21 @@ 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(); From 16c3aa43e4fb6eba4c887007ba0b060de824549c Mon Sep 17 00:00:00 2001 From: johnthagen Date: Thu, 28 Sep 2017 10:42:53 -0400 Subject: [PATCH 5/7] Add instructions for adding OpenSSL DLLs to PATH if needed during install --- README.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/README.md b/README.md index c505efd3..4d05ec13 100644 --- a/README.md +++ b/README.md @@ -88,6 +88,13 @@ installation via an environment variable: set OPENSSL_DIR=C:\OpenSSL-Win64 ``` +During the installation process if you select "Copy OpenSSL DLLs to: The OpenSSL binaries (/bin) +directory", you will need to add them to the `PATH` environment variable: + +``` +set PATH=%PATH%;C:\OpenSSL-Win64\bin +``` + Now you will need to [install root certificates.](#acquiring-root-certificates) #### Installing OpenSSL 1.0.2 using vcpkg From c5aef19d052698efd6e1a4f5206ddefe3bf00223 Mon Sep 17 00:00:00 2001 From: johnthagen Date: Thu, 28 Sep 2017 13:34:49 -0400 Subject: [PATCH 6/7] Add instructions for adding OpenSSL DLLs to PATH if needed during install --- openssl/src/memcmp.rs | 51 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) 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 { From b65540709fce62edbc07b87e71310367a5acefb7 Mon Sep 17 00:00:00 2001 From: johnthagen Date: Thu, 28 Sep 2017 14:25:39 -0400 Subject: [PATCH 7/7] Document nid module --- openssl/src/nid.rs | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) 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 }