diff options
| -rw-r--r-- | README.md | 7 | ||||
| -rw-r--r-- | openssl/src/aes.rs | 63 | ||||
| -rw-r--r-- | openssl/src/memcmp.rs | 51 | ||||
| -rw-r--r-- | openssl/src/nid.rs | 28 |
4 files changed, 147 insertions, 2 deletions
@@ -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 diff --git a/openssl/src/aes.rs b/openssl/src/aes.rs index 40546f59..5be99430 100644 --- a/openssl/src/aes.rs +++ b/openssl/src/aes.rs @@ -1,15 +1,62 @@ -//! Low level AES functionality +//! Low level AES IGE functionality //! -//! The `symm` module should be used in preference to this module in most cases. +//! AES ECB, CBC, XTS, CTR, CFB, GCM and other conventional symmetric encryption +//! modes are found in [`symm`]. This is the implementation of AES IGE. +//! +//! Advanced Encryption Standard (AES) provides symmetric key cipher that +//! the same key is used to encrypt and decrypt data. This implementation +//! uses 128, 192, or 256 bit keys. This module provides functions to +//! create a new key with [`new_encrypt`] and perform an encryption/decryption +//! using that key with [`aes_ige`]. +//! +//! [`new_encrypt`]: struct.AesKey.html#method.new_encrypt +//! [`aes_ige`]: fn.aes_ige.html +//! +//! The [`symm`] module should be used in preference to this module in most cases. +//! The IGE block cypher is a non-traditional cipher mode. More traditional AES +//! encryption methods are found in the [`Crypter`] and [`Cipher`] structs. +//! +//! [`symm`]: ../symm/index.html +//! [`Crypter`]: ../symm/struct.Crypter.html +//! [`Cipher`]: ../symm/struct.Cipher.html +//! +//! # Examples +//! +//! ```rust +//! # extern crate openssl; +//! extern crate hex; +//! use openssl::aes::{AesKey, KeyError, aes_ige}; +//! use openssl::symm::Mode; +//! use hex::{FromHex, ToHex}; +//! +//! fn decrypt() -> Result<(), KeyError> { +//! let raw_key = "000102030405060708090A0B0C0D0E0F"; +//! let hex_cipher = "12345678901234561234567890123456"; +//! let randomness = "000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F"; +//! if let (Ok(key_as_u8), Ok(cipher_as_u8), Ok(mut iv_as_u8)) = +//! (Vec::from_hex(raw_key), Vec::from_hex(hex_cipher), Vec::from_hex(randomness)) { +//! let key = AesKey::new_encrypt(&key_as_u8)?; +//! let mut output = vec![0u8; cipher_as_u8.len()]; +//! aes_ige(&cipher_as_u8, &mut output, &key, &mut iv_as_u8, Mode::Encrypt); +//! assert_eq!(output.to_hex(), "a6ad974d5cea1d36d2f367980907ed32"); +//! } +//! Ok(()) +//! } +//! +//! # fn main() { +//! # decrypt(); +//! # } use ffi; use std::mem; use libc::c_int; use symm::Mode; +/// Provides Error handling for parsing keys. #[derive(Debug)] pub struct KeyError(()); +/// The key used to encrypt or decrypt cipher blocks. pub struct AesKey(ffi::AES_KEY); impl AesKey { @@ -63,6 +110,18 @@ impl AesKey { /// Performs AES IGE encryption or decryption /// +/// AES IGE (Infinite Garble Extension) is a form of AES block cipher utilized in +/// OpenSSL. Infinite Garble referes to propogating forward errors. IGE, like other +/// block ciphers implemented for AES requires an initalization vector. The IGE mode +/// allows a stream of blocks to be encrypted or decrypted without having the entire +/// plaintext available. For more information, visit [AES IGE Encryption]. +/// +/// This block cipher uses 16 byte blocks. The rust implmentation will panic +/// if the input or output does not meet this 16-byte boundry. Attention must +/// be made in this low level implementation to pad the value to the 128-bit boundry. +/// +/// [AES IGE Encryption]: http://www.links.org/files/openssl-ige.pdf +/// /// # Panics /// /// Panics if `in_` is not the same length as `out`, if that length is not a multiple of 16, or if 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 } |