Struct Cipher 

pub struct Cipher { /* private fields */ }

Provides encryption and decryption functions for AES in modes ECB, CTR, and GCM. Instantiated with an AES Key, which is expanded into round keys and stored in the instance.

Examples

use aesp::{Key, Cipher};
 
// Instantiate random key:
let rk_256 = Key::rand_key_256()?;
 
// Instantiate AESP cipher using the key:
let cipher = Cipher::new(&rk_256);

Implementations

impl Cipher

pub fn new(key: &Key) -> Self

Generates round keys from provided key and stores in the returned instance.

pub fn round_keys(&self) -> &[[u8; 16]]

Getter for internal round keys. Returned as a slice of 16-byte arrays.

pub fn encrypt_ecb(&self, plaintext: &[u8]) -> Vec<u8>

Electronic codebook encryption.

Encrypts each 16-byte block entirely independently and chains them together. Pads input to a multiple of 16 bytes using PKCS#7 padding. Vulnerable to pattern emergence in the ciphertext.

Examples

let plaintext = ("Hello, World!").as_bytes();
let ciphertext = cipher.encrypt_ecb(&plaintext);

pub fn decrypt_ecb(&self, ciphertext: &[u8]) -> Result<Vec<u8>>

Electronic codebook decryption.

Assumes plaintext was PKCS#7 padded before encryption and unpads automatically. Throws error if last block does not match PKCS#7 format or input is not a multiple of 16 bytes.

Examples

let plaintext = ("Hello, World!").as_bytes();
let ciphertext = cipher.encrypt_ecb(&plaintext);
let decrypted = cipher.decrypt_ecb(&ciphertext)?;
assert_eq!(decrypted, plaintext);

pub fn encrypt_ctr(&self, plaintext: &[u8]) -> Result<Vec<u8>>

Counter mode encryption.

Generates a random 12-byte initialisation vector (IV). For each 16-byte block of plaintext:

1. 4-byte counter is incremented (starts at zero).
2. Counter is appended to 12-byte IV to form a 16-byte block.
3. The IV || Counter block is encrypted using the round keys.
4. The plaintext block is XOR’d with the encrypted counter block.

Important: the same IV must never be reused with the same key. 96 bits is sufficiently large to assume uniqueness when randomly generated.

Output is formatted as IV (12 bytes) || Ciphertext

Examples

let plaintext = ("Hello, World!").as_bytes();
let ciphertext = cipher.encrypt_ctr(&plaintext)?;

pub fn decrypt_ctr(&self, ciphertext: &[u8]) -> Result<Vec<u8>>

Counter mode decryption.

Assumes format matches output of encryption: IV (12 bytes) || Ciphertext

Examples

let plaintext = ("Hello, World!").as_bytes();
let ciphertext = cipher.encrypt_ctr(&plaintext)?;
let decrypted = cipher.decrypt_ctr(&ciphertext)?;
assert_eq!(decrypted, plaintext);

pub fn encrypt_gcm( &self, plaintext: &[u8], aad: Option<&[u8]>, ) -> Result<Vec<u8>>

Galois/counter mode encryption.

Encrypts using counter mode and generates a cryptographic tag to verify the message has not been modified.

Also accepts optional additional authenticated data (AAD), which is included in the computation of the tag but not encrypted.

Output is formatted as IV (12 bytes) || AAD length (4 bytes) || AAD || Ciphertext || Tag (16 bytes)

Examples

let plaintext = ("Hello, World!").as_bytes();
let aad = ("Some data to be authenticated but not encrypted").as_bytes();

let ciphertext_with_aad = cipher.encrypt_gcm(plaintext, Some(aad))?;
let ciphertext_no_aad = cipher.encrypt_gcm(plaintext, None)?;

pub fn decrypt_gcm( &self, ciphertext: &[u8], ) -> Result<(Vec<u8>, Option<Vec<u8>>)>

Galois/counter mode decryption.

Assumes input follows the same format as encryption: IV (12 bytes) || AAD length (4 bytes) || AAD || Ciphertext || Tag (16 bytes)

Returns:

• (plaintext, AAD) if tag was authenticated and decryption was successful.
• AuthFailed error if computed tag did not match input tag.
• CounterOverflow error if more than 2^32 blocks were provided.
• InvalidCiphertext error if ciphertext does not match expected format.

Examples

let plaintext = ("Hello, World!").as_bytes();
let aad = ("Some data to be authenticated but not encrypted").as_bytes();

// Decryption with AAD
let ciphertext = cipher.encrypt_gcm(plaintext, Some(aad))?;
let (decrypted, returned_aad) = cipher.decrypt_gcm(&ciphertext)?;

assert_eq!(decrypted, plaintext);
assert_eq!(returned_aad, Some(aad.to_vec()));

// Decryption without AAD
let ciphertext = cipher.encrypt_gcm(plaintext, None)?;
let (_, returned_aad) = cipher.decrypt_gcm(&ciphertext)?;
assert!(returned_aad.is_none());

Trait Implementations

impl Clone for Cipher

fn clone(&self) -> Cipher

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Cipher

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq for Cipher

fn eq(&self, other: &Cipher) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for Cipher

impl StructuralPartialEq for Cipher