aws_lc_rs

Module cipher

Source
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§

Enums§

Constants§

  • AES_128_KEY_LEN
    The number of bytes in an AES 128-bit key Length of an AES-128 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§