Module cipher

Expand description

Block and Stream Ciphers for Encryption and Decryption.

§🛑 Read Before Using

This module provides access to block and stream cipher algorithms. The modes provided here only provide confidentiality, but do not provide integrity or authentication verification of ciphertext.

These algorithms are provided solely for applications requiring them in order to maintain backwards compatibility in legacy applications.

If you are developing new applications requiring data encryption see the algorithms provided in aead.

§Examples

§Encryption Modes

§AES-128 CBC

use aws_lc_rs::cipher::{
    PaddedBlockDecryptingKey, PaddedBlockEncryptingKey, UnboundCipherKey, AES_128,
};
use std::io::Read;

let original_message = "This is a secret message!".as_bytes();
let mut in_out_buffer = Vec::from(original_message);

let key_bytes: &[u8] = &[
    0xff, 0x0b, 0xe5, 0x84, 0x64, 0x0b, 0x00, 0xc8, 0x90, 0x7a, 0x4b, 0xbf, 0x82, 0x7c, 0xb6,
    0xd1,
];

let key = UnboundCipherKey::new(&AES_128, key_bytes)?;
let mut encrypting_key = PaddedBlockEncryptingKey::cbc_pkcs7(key)?;
let context = encrypting_key.encrypt(&mut in_out_buffer)?;

let key = UnboundCipherKey::new(&AES_128, key_bytes)?;
let mut decrypting_key = PaddedBlockDecryptingKey::cbc_pkcs7(key)?;
let plaintext = decrypting_key.decrypt(&mut in_out_buffer, context)?;
assert_eq!(original_message, plaintext);

§AES-128 CTR

use aws_lc_rs::cipher::{DecryptingKey, EncryptingKey, UnboundCipherKey, AES_128};

let original_message = "This is a secret message!".as_bytes();
let mut in_out_buffer = Vec::from(original_message);

let key_bytes: &[u8] = &[
    0xff, 0x0b, 0xe5, 0x84, 0x64, 0x0b, 0x00, 0xc8, 0x90, 0x7a, 0x4b, 0xbf, 0x82, 0x7c, 0xb6,
    0xd1,
];

let key = UnboundCipherKey::new(&AES_128, key_bytes)?;
let mut encrypting_key = EncryptingKey::ctr(key)?;
let context = encrypting_key.encrypt(&mut in_out_buffer)?;

let key = UnboundCipherKey::new(&AES_128, key_bytes)?;
let mut decrypting_key = DecryptingKey::ctr(key)?;
let plaintext = decrypting_key.decrypt(&mut in_out_buffer, context)?;
assert_eq!(original_message, plaintext);

§AES-128 CBC Streaming Cipher

use aws_lc_rs::cipher::{
    StreamingDecryptingKey, StreamingEncryptingKey, UnboundCipherKey, AES_128,
};
let original_message = "This is a secret message!".as_bytes();
let key_bytes: &[u8] = &[
    0xff, 0x0b, 0xe5, 0x84, 0x64, 0x0b, 0x00, 0xc8, 0x90, 0x7a, 0x4b, 0xbf, 0x82, 0x7c,
    0xb6, 0xd1,
];
// Prepare ciphertext buffer
let mut ciphertext_buffer = vec![0u8; original_message.len() + AES_128.block_len()];
let ciphertext_slice = ciphertext_buffer.as_mut_slice();

// Create StreamingEncryptingKey
let key = UnboundCipherKey::new(&AES_128, key_bytes).unwrap();
let mut encrypting_key = StreamingEncryptingKey::cbc_pkcs7(key).unwrap();

// Encrypt
let mut first_update = encrypting_key
                           .update(original_message, ciphertext_slice)
                           .unwrap();
let first_update_len = first_update.written().len();
let (context, final_update) = encrypting_key.finish(first_update.remainder_mut()).unwrap();
let ciphertext_len = first_update_len + final_update.written().len();
let ciphertext = &ciphertext_slice[0..ciphertext_len];

// Prepare plaintext buffer
let mut plaintext_buffer = vec![0u8; ciphertext_len + AES_128.block_len()];
let plaintext_slice = plaintext_buffer.as_mut_slice();

// Create StreamingDecryptingKey
let key = UnboundCipherKey::new(&AES_128, key_bytes).unwrap();
let mut decrypting_key = StreamingDecryptingKey::cbc_pkcs7(key, context).unwrap();

// Decrypt
let mut first_update = decrypting_key.update(ciphertext, plaintext_slice).unwrap();
let first_update_len = first_update.written().len();
let final_update = decrypting_key.finish(first_update.remainder_mut()).unwrap();
let plaintext_len = first_update_len + final_update.written().len();
let plaintext = &plaintext_slice[0..plaintext_len];

assert_eq!(original_message, plaintext);

§AES-128 CFB 128-bit mode

use aws_lc_rs::cipher::{DecryptingKey, EncryptingKey, UnboundCipherKey, AES_128};

let original_message = "This is a secret message!".as_bytes();
let mut in_out_buffer = Vec::from(original_message);

let key_bytes: &[u8] = &[
    0xff, 0x0b, 0xe5, 0x84, 0x64, 0x0b, 0x00, 0xc8, 0x90, 0x7a, 0x4b, 0xbf, 0x82, 0x7c, 0xb6,
    0xd1,
];

let key = UnboundCipherKey::new(&AES_128, key_bytes)?;
let mut encrypting_key = EncryptingKey::cfb128(key)?;
let context = encrypting_key.encrypt(&mut in_out_buffer)?;

let key = UnboundCipherKey::new(&AES_128, key_bytes)?;
let mut decrypting_key = DecryptingKey::cfb128(key)?;
let plaintext = decrypting_key.decrypt(&mut in_out_buffer, context)?;
assert_eq!(original_message, plaintext);

§Constructing a `DecryptionContext` for decryption.

use aws_lc_rs::cipher::{DecryptingKey, DecryptionContext, UnboundCipherKey, AES_128};
use aws_lc_rs::iv::{FixedLength, IV_LEN_128_BIT};

let context = DecryptionContext::Iv128(FixedLength::<IV_LEN_128_BIT>::from(&[
    0x8d, 0xdb, 0x7d, 0xf1, 0x56, 0xf5, 0x1c, 0xde, 0x63, 0xe3, 0x4a, 0x34, 0xb0, 0xdf, 0x28,
    0xf0,
]));

let ciphertext: &[u8] = &[
    0x79, 0x8c, 0x04, 0x58, 0xcf, 0x98, 0xb1, 0xe9, 0x97, 0x6b, 0xa1, 0xce,
];

let mut in_out_buffer = Vec::from(ciphertext);

let key = UnboundCipherKey::new(
    &AES_128,
    &[
        0x5b, 0xfc, 0xe7, 0x5e, 0x57, 0xc5, 0x4d, 0xda, 0x2d, 0xd4, 0x7e, 0x07, 0x0a, 0xef,
        0x43, 0x29,
    ],
)?;
let mut decrypting_key = DecryptingKey::ctr(key)?;
let plaintext = decrypting_key.decrypt(&mut in_out_buffer, context)?;
assert_eq!("Hello World!".as_bytes(), plaintext);

§Getting an immutable reference to the IV slice.

TryFrom<&DecryptionContext> is implemented for &[u8] allowing immutable references to IV bytes returned from cipher encryption operations. Note this is implemented as a TryFrom as it may fail for future enum variants that aren’t representable as a single slice.

// x is type `DecryptionContext`
let iv: &[u8] = (&x).try_into()?;

Structs§

Algorithm: A cipher algorithm.
BufferUpdate: A struct indicating the portion of a buffer written to, and/or not written to, during an encryption/decryption operation.
DecryptingKey: A cipher decryption key that does not perform block padding.
EncryptingKey: A cipher encryption key that does not perform block padding.
PaddedBlockDecryptingKey: A cipher decryption key that performs block padding.
PaddedBlockEncryptingKey: A cipher encryption key that performs block padding.
StreamingDecryptingKey: A key for streaming decryption operations.
StreamingEncryptingKey: A key for streaming encryption operations.
UnboundCipherKey: A key bound to a particular cipher algorithm.

Enums§

AlgorithmId: Cipher algorithm identifier.
DecryptionContext: The contextual data used to encrypt or decrypt data.
EncryptionContext: The contextual data used to encrypt or decrypt data.
OperatingMode: The cipher operating mode.

Constants§

AES_128_KEY_LEN: The number of bytes in an AES 128-bit key Length of an AES-128 key in bytes.
AES_192_KEY_LEN: The number of bytes in an AES 192-bit key Length of an AES-192 key in bytes.
AES_256_KEY_LEN: The number of bytes in an AES 256-bit key Length of an AES-256 key in bytes.
AES_CBC_IV_LEN: The number of bytes for an AES-CBC initialization vector (IV) The number of bytes for an AES-CBC initialization vector (IV)
AES_CFB_IV_LEN: The number of bytes for an AES-CFB initialization vector (IV) The number of bytes for an AES-CFB initialization vector (IV)
AES_CTR_IV_LEN: The number of bytes for an AES-CTR initialization vector (IV) The number of bytes for an AES-CTR initialization vector (IV)

Statics§

AES_128: AES 128-bit cipher
AES_192: AES 192-bit cipher
AES_256: AES 256-bit cipher

Module cipherCopy item path