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
impl Crypter
sourcepub fn new(
t: Cipher,
mode: Mode,
key: &[u8],
iv: Option<&[u8]>,
) -> Result<Crypter, ErrorStack>
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.
sourcepub fn pad(&mut self, padding: bool)
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.
sourcepub fn set_tag(&mut self, tag: &[u8]) -> Result<(), ErrorStack>
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
.
sourcepub fn set_tag_len(&mut self, tag_len: usize) -> Result<(), ErrorStack>
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.
sourcepub fn set_data_len(&mut self, data_len: usize) -> Result<(), ErrorStack>
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.
sourcepub fn aad_update(&mut self, input: &[u8]) -> Result<(), ErrorStack>
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
.
sourcepub fn update(
&mut self,
input: &[u8],
output: &mut [u8],
) -> Result<usize, ErrorStack>
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
.
sourcepub unsafe fn update_unchecked(
&mut self,
input: &[u8],
output: &mut [u8],
) -> Result<usize, ErrorStack>
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.
sourcepub fn finalize(&mut self, output: &mut [u8]) -> Result<usize, ErrorStack>
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
).
sourcepub fn get_tag(&self, tag: &mut [u8]) -> Result<(), ErrorStack>
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.