Struct Cipher 

pub struct Cipher { /* private fields */ }

Stateful symmetric cipher context.

See the module-level documentation for the cycle of life and the buffer ownership model.

Implementations

impl Cipher

pub fn new(algo: Algorithm, mode: Mode, padding: Padding) -> Result<Self, Error>

Create a new cipher context with the given algorithm, mode and padding scheme. Validates that the combination is supported; the actual key and IV are loaded later by Self::init.

Errors

Returns Error::InvalidPaddingForMode when the requested padding is incompatible with the requested mode (e.g. any padding other than None with Mode::Ctr).

pub fn init( &mut self, direction: Direction, key: &[u8], iv: &[u8], ) -> Result<(), Error>

Initialise (or re-initialise) the context with a key, IV and direction. Loading a new key wipes any pending input from a previous run, so the same Cipher object can be reused across many independent encryptions or decryptions.

iv must be block_len() bytes long for CBC and CTR; for ECB the slice is ignored but a &[] is the conventional choice.

Errors

• Error::InvalidKeyLen if key.len() does not match the algorithm.
• Error::InvalidIvLen if iv.len() does not match the block size for a mode that requires an IV.

pub const fn block_len(&self) -> usize

Block size of the underlying cipher in bytes (16 for AES, 8 for DES / 3DES).

pub const fn iv_len(&self) -> usize

IV / nonce length expected by Self::init for the configured mode. Returns 0 for ECB.

pub fn update_output_size(&self, input_len: usize) -> usize

Safe upper bound on the number of bytes a single Self::update call would write into output, given an input_len-byte input. Use this to size caller-provided buffers.

pub const fn finalize_output_size(&self) -> usize

Safe upper bound on the number of bytes Self::finalize would write into output. Always at most one block.

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

Feed input bytes through the cipher and write any complete output bytes into output. Returns the number of bytes actually written.

Either slice may be empty. Bytes that don’t yet form a full output block stay buffered inside the Cipher until enough data arrives or Self::finalize is called.

Errors

• Error::NotInitialized if Self::init has not been called.
• Error::AlreadyFinalized if Self::finalize has already run.
• Error::OutputBufferTooSmall if output is shorter than the number of bytes the call would write.

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

Finish the operation: pad and emit the trailing block (encrypt) or strip the padding from the last buffered ciphertext block (decrypt). After this call the context is in a finalized state and must be re-initialised with Self::init before further use.

Errors

• Error::NotInitialized if Self::init has not been called.
• Error::AlreadyFinalized if finalize has already run.
• Error::OutputBufferTooSmall if output is too small.
• Error::UnpaddedInput if Padding::None was selected and the total input length is not a multiple of the block size.
• Error::BadPadding (decryption only) if the trailing plaintext does not match the declared padding scheme.

pub fn update_to_vec(&mut self, input: &[u8]) -> Result<Vec<u8>, Error>

Convenience wrapper around Self::update that returns the freshly produced bytes as a Vec<u8>. Allocates.

pub fn finalize_to_vec(&mut self) -> Result<Vec<u8>, Error>

Convenience wrapper around Self::finalize that returns the trailing bytes as a Vec<u8>. Allocates.