Struct openssl::symm::Crypter

source ·
pub struct Crypter { /* private fields */ }
Expand description

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§

source§

impl Crypter

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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).

source

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.

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.