Merge pull request #734 from AndyGauge/doc-aes

//! 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 {

/// 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