From b07b0e7fb783fe8e9c0d7b697742273885c496b2 Mon Sep 17 00:00:00 2001 From: Andy Gauge Date: Mon, 25 Sep 2017 17:01:08 -0700 Subject: [PATCH 1/5] WIP: document AES --- openssl/src/aes.rs | 31 ++++++++++++++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) diff --git a/openssl/src/aes.rs b/openssl/src/aes.rs index 40546f59..19089dee 100644 --- a/openssl/src/aes.rs +++ b/openssl/src/aes.rs @@ -1,6 +1,35 @@ //! Low level AES functionality //! -//! The `symm` module should be used in preference to this module in most cases. +//! 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. +//! +//! [`symm`]: ../symm/index.html +//! +//! # Examples +//! +//! ```rust +//! # extern crate openssl; +//! extern crate hex; +//! use openssl::aes::{AesKey, KeyError}; +//! use hex::FromHex; +//! +//! fn decrypt() -> Result<(), KeyError> { +//! let raw_key = "000102030405060708090A0B0C0D0E0F"; +//! let key = AesKey::new_encrypt(&Vec::from_hex(raw_key).unwrap())?; +//! Ok(()) +//! } +//! +//! # fn main() { +//! # decrypt(); +//! # } use ffi; use std::mem; use libc::c_int; From afde5a84b143babdbb8c48bd932d1c64c56ddd31 Mon Sep 17 00:00:00 2001 From: Andy Gauge Date: Tue, 26 Sep 2017 16:34:06 -0700 Subject: [PATCH 2/5] AES Module level docs and example --- openssl/src/aes.rs | 27 ++++++++++++++++++++------- 1 file changed, 20 insertions(+), 7 deletions(-) diff --git a/openssl/src/aes.rs b/openssl/src/aes.rs index 19089dee..c7e744ae 100644 --- a/openssl/src/aes.rs +++ b/openssl/src/aes.rs @@ -6,6 +6,10 @@ //! create a new key with [`new_encrypt`] and perform an encryption/decryption //! using that key with [`aes_ige`]. //! +//! AES is a 128-bit (16 byte) block cipher. 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. +//! //! [`new_encrypt`]: struct.AesKey.html#method.new_encrypt //! [`aes_ige`]: fn.aes_ige.html //! @@ -18,17 +22,26 @@ //! ```rust //! # extern crate openssl; //! extern crate hex; -//! use openssl::aes::{AesKey, KeyError}; -//! use hex::FromHex; +//! use openssl::aes::{AesKey, KeyError, aes_ige}; +//! use openssl::symm::Mode; +//! use hex::{FromHex, ToHex}; //! //! fn decrypt() -> Result<(), KeyError> { -//! let raw_key = "000102030405060708090A0B0C0D0E0F"; -//! let key = AesKey::new_encrypt(&Vec::from_hex(raw_key).unwrap())?; -//! Ok(()) +//! 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(); +//! # decrypt(); //! # } use ffi; use std::mem; From ad879ad7dea7548385277cbce8c6dd35284df4b0 Mon Sep 17 00:00:00 2001 From: Andy Gauge Date: Tue, 26 Sep 2017 16:51:37 -0700 Subject: [PATCH 3/5] AES (IGE) encryption documentation --- openssl/src/aes.rs | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/openssl/src/aes.rs b/openssl/src/aes.rs index c7e744ae..d128a666 100644 --- a/openssl/src/aes.rs +++ b/openssl/src/aes.rs @@ -49,9 +49,11 @@ 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 { @@ -105,6 +107,14 @@ impl AesKey { /// Performs AES IGE encryption or decryption /// +/// AES IGE (Infinite Garble Extension) is the 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]. +/// +/// [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 From f759f8dd4a25ae96a015078fdf728bf584278731 Mon Sep 17 00:00:00 2001 From: Andy Gauge Date: Wed, 27 Sep 2017 08:46:13 -0700 Subject: [PATCH 4/5] Preface with links to conventional AES --- openssl/src/aes.rs | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/openssl/src/aes.rs b/openssl/src/aes.rs index d128a666..7c008575 100644 --- a/openssl/src/aes.rs +++ b/openssl/src/aes.rs @@ -1,8 +1,11 @@ -//! Low level AES functionality +//! Low level AES IGE functionality +//! +//! 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 +//! 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`]. //! @@ -14,8 +17,12 @@ //! [`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 //! @@ -107,7 +114,7 @@ impl AesKey { /// Performs AES IGE encryption or decryption /// -/// AES IGE (Infinite Garble Extension) is the form of AES block cipher utilized in +/// 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 From 1e3b8183bbd8e8cdbf517760a78bc1d37383e317 Mon Sep 17 00:00:00 2001 From: Andy Gauge Date: Thu, 28 Sep 2017 08:04:10 -0700 Subject: [PATCH 5/5] Moved details about function and reworded block requirements --- openssl/src/aes.rs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/openssl/src/aes.rs b/openssl/src/aes.rs index 7c008575..5be99430 100644 --- a/openssl/src/aes.rs +++ b/openssl/src/aes.rs @@ -9,10 +9,6 @@ //! create a new key with [`new_encrypt`] and perform an encryption/decryption //! using that key with [`aes_ige`]. //! -//! AES is a 128-bit (16 byte) block cipher. 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. -//! //! [`new_encrypt`]: struct.AesKey.html#method.new_encrypt //! [`aes_ige`]: fn.aes_ige.html //! @@ -120,6 +116,10 @@ impl AesKey { /// 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