Struct Crypter

pub struct Crypter { /* private fields */ }

Represents a symmetric cipher context.

Padding is enabled by default.

Examples

Encrypt some plaintext in chunks, then decrypt the ciphertext back into plaintext, in AES 128 CBC mode.

use openssl::symm::{Cipher, Mode, Crypter};

let plaintexts: [&[u8]; 2] = [b"Some Stream of", b" Crypto Text"];
let key = b"\x00\x01\x02\x03\x04\x05\x06\x07\x08\x09\x0A\x0B\x0C\x0D\x0E\x0F";
let iv = b"\x00\x01\x02\x03\x04\x05\x06\x07\x00\x01\x02\x03\x04\x05\x06\x07";
let data_len = plaintexts.iter().fold(0, |sum, x| sum + x.len());

// Create a cipher context for encryption.
let mut encrypter = Crypter::new(
    Cipher::aes_128_cbc(),
    Mode::Encrypt,
    key,
    Some(iv)).unwrap();

let block_size = Cipher::aes_128_cbc().block_size();
let mut ciphertext = vec![0; data_len + block_size];

// Encrypt 2 chunks of plaintexts successively.
let mut count = encrypter.update(plaintexts[0], &mut ciphertext).unwrap();
count += encrypter.update(plaintexts[1], &mut ciphertext[count..]).unwrap();
count += encrypter.finalize(&mut ciphertext[count..]).unwrap();
ciphertext.truncate(count);

assert_eq!(
    b"\x0F\x21\x83\x7E\xB2\x88\x04\xAF\xD9\xCC\xE2\x03\x49\xB4\x88\xF6\xC4\x61\x0E\x32\x1C\xF9\
      \x0D\x66\xB1\xE6\x2C\x77\x76\x18\x8D\x99",
    &ciphertext[..]
);


// Let's pretend we don't know the plaintext, and now decrypt the ciphertext.
let data_len = ciphertext.len();
let ciphertexts = [&ciphertext[..9], &ciphertext[9..]];

// Create a cipher context for decryption.
let mut decrypter = Crypter::new(
    Cipher::aes_128_cbc(),
    Mode::Decrypt,
    key,
    Some(iv)).unwrap();
let mut plaintext = vec![0; data_len + block_size];

// Decrypt 2 chunks of ciphertexts successively.
let mut count = decrypter.update(ciphertexts[0], &mut plaintext).unwrap();
count += decrypter.update(ciphertexts[1], &mut plaintext[count..]).unwrap();
count += decrypter.finalize(&mut plaintext[count..]).unwrap();
plaintext.truncate(count);

assert_eq!(b"Some Stream of Crypto Text", &plaintext[..]);

Implementations

impl Crypter

pub fn new( t: Cipher, mode: Mode, key: &[u8], iv: Option<&[u8]>, ) -> Result<Crypter, ErrorStack>

Creates a new Crypter. The initialisation vector, iv, is not necessary for certain types of Cipher.

Panics

Panics if an IV is required by the cipher but not provided. Also make sure that the key and IV size are appropriate for your cipher.

pub fn pad(&mut self, padding: bool)

Enables or disables padding.

If padding is disabled, total amount of data encrypted/decrypted must be a multiple of the cipher’s block size.

pub fn set_tag(&mut self, tag: &[u8]) -> Result<(), ErrorStack>

Sets the tag used to authenticate ciphertext in AEAD ciphers such as AES GCM.

When decrypting cipher text using an AEAD cipher, this must be called before finalize.

pub fn set_tag_len(&mut self, tag_len: usize) -> Result<(), ErrorStack>

Sets the length of the authentication tag to generate in AES CCM.

When encrypting with AES CCM, the tag length needs to be explicitly set in order to use a value different than the default 12 bytes.

pub fn set_data_len(&mut self, data_len: usize) -> Result<(), ErrorStack>

Feeds total plaintext length to the cipher.

The total plaintext or ciphertext length MUST be passed to the cipher when it operates in CCM mode.

pub fn aad_update(&mut self, input: &[u8]) -> Result<(), ErrorStack>

Feeds Additional Authenticated Data (AAD) through the cipher.

This can only be used with AEAD ciphers such as AES GCM. Data fed in is not encrypted, but is factored into the authentication tag. It must be called before the first call to update.

pub fn update( &mut self, input: &[u8], output: &mut [u8], ) -> Result<usize, ErrorStack>

Feeds data from input through the cipher, writing encrypted/decrypted bytes into output.

The number of bytes written to output is returned. Note that this may not be equal to the length of input.

Panics

Panics for stream ciphers if output.len() < input.len().

Panics for block ciphers if output.len() < input.len() + block_size, where block_size is the block size of the cipher (see Cipher::block_size).

Panics if output.len() > c_int::MAX.

pub unsafe fn update_unchecked( &mut self, input: &[u8], output: &mut [u8], ) -> Result<usize, ErrorStack>

Feeds data from input through the cipher, writing encrypted/decrypted bytes into output.

The number of bytes written to output is returned. Note that this may not be equal to the length of input.

Safety

The caller must provide an output buffer large enough to contain correct number of bytes. For streaming ciphers the output buffer size should be at least as big as the input buffer. For block ciphers the size of the output buffer depends on the state of partially updated blocks.

pub fn finalize(&mut self, output: &mut [u8]) -> Result<usize, ErrorStack>

Finishes the encryption/decryption process, writing any remaining data to output.

The number of bytes written to output is returned.

update should not be called after this method.

Panics

Panics for block ciphers if output.len() < block_size, where block_size is the block size of the cipher (see Cipher::block_size).

pub fn get_tag(&self, tag: &mut [u8]) -> Result<(), ErrorStack>

Retrieves the authentication tag used to authenticate ciphertext in AEAD ciphers such as AES GCM.

When encrypting data with an AEAD cipher, this must be called after finalize.

The size of the buffer indicates the required size of the tag. While some ciphers support a range of tag sizes, it is recommended to pick the maximum size. For AES GCM, this is 16 bytes, for example.