Struct openssl::symm::Crypter

pub struct Crypter { /* fields omitted */ }

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[..]);

Methods

impl Crypter

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

Creates a new Crypter. The initialisation vector, iv, is not necesarry 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.

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.

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.

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.

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 if output.len() < input.len() + block_size where block_size is the block size of the cipher (see Cipher::block_size), or if output.len() > c_int::max_value().

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 if output is less than the cipher's block size.

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.

Trait Implementations

impl Drop for Crypter

fn drop(&mut self)

Executes the destructor for this type.