Struct CipherCtx

source

pub struct CipherCtx(/* private fields */);

Expand description

A context object used to perform symmetric encryption operations.

Implementations§

source §

impl CipherCtx

source

pub fn new() -> Result<Self, ErrorStack>

Creates a new context.

This corresponds to EVP_CIPHER_CTX_new.

Methods from Deref<Target = CipherCtxRef>§

source

pub fn copy(&mut self, src: &CipherCtxRef) -> Result<(), ErrorStack>

This corresponds to EVP_CIPHER_CTX_copy.

source

pub fn encrypt_init( &mut self, type_: Option<&CipherRef>, key: Option<&[u8]>, iv: Option<&[u8]>, ) -> Result<(), ErrorStack>

Initializes the context for encryption.

Normally this is called once to set all of the cipher, key, and IV. However, this process can be split up by first setting the cipher with no key or IV and then setting the key and IV with no cipher. This can be used to, for example, use a nonstandard IV size.

§Panics

Panics if the key buffer is smaller than the key size of the cipher, the IV buffer is smaller than the IV size of the cipher, or if a key or IV is provided before a cipher.

This corresponds to EVP_EncryptInit_ex.

source

pub fn decrypt_init( &mut self, type_: Option<&CipherRef>, key: Option<&[u8]>, iv: Option<&[u8]>, ) -> Result<(), ErrorStack>

Initializes the context for decryption.

Normally this is called once to set all of the cipher, key, and IV. However, this process can be split up by first setting the cipher with no key or IV and then setting the key and IV with no cipher. This can be used to, for example, use a nonstandard IV size.

§Panics

Panics if the key buffer is smaller than the key size of the cipher, the IV buffer is smaller than the IV size of the cipher, or if a key or IV is provided before a cipher.

This corresponds to EVP_DecryptInit_ex.

source

pub fn seal_init<T>( &mut self, type_: Option<&CipherRef>, pub_keys: &[PKey<T>], encrypted_keys: &mut [Vec<u8>], iv: Option<&mut [u8]>, ) -> Result<(), ErrorStack>
where T: HasPublic,

Initializes the context to perform envelope encryption.

Normally this is called once to set both the cipher and public keys. However, this process may be split up by first providing the cipher with no public keys and then setting the public keys with no cipher.

encrypted_keys will contain the generated symmetric key encrypted with each corresponding asymmetric private key. The generated IV will be written to iv.

§Panics

Panics if pub_keys is not the same size as encrypted_keys, the IV buffer is smaller than the cipher’s IV size, or if an IV is provided before the cipher.

This corresponds to EVP_SealInit.

source

pub fn open_init<T>( &mut self, type_: Option<&CipherRef>, encrypted_key: &[u8], iv: Option<&[u8]>, priv_key: Option<&PKeyRef<T>>, ) -> Result<(), ErrorStack>
where T: HasPrivate,

Initializes the context to perform envelope decryption.

Normally this is called once with all of the arguments present. However, this process may be split up by first providing the cipher alone and then after providing the rest of the arguments in a second call.

§Panics

Panics if the IV buffer is smaller than the cipher’s required IV size or if the IV is provided before the cipher.

This corresponds to EVP_OpenInit.

source

pub fn block_size(&self) -> usize

Returns the block size of the context’s cipher.

Stream ciphers will report a block size of 1.

§Panics

Panics if the context has not been initialized with a cipher.

This corresponds to EVP_CIPHER_CTX_block_size.

source

pub fn key_length(&self) -> usize

Returns the key length of the context’s cipher.

§Panics

Panics if the context has not been initialized with a cipher.

This corresponds to EVP_CIPHER_CTX_key_length.

source

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

Generates a random key based on the configured cipher.

§Panics

Panics if the context has not been initialized with a cipher or if the buffer is smaller than the cipher’s key length.

This corresponds to EVP_CIPHER_CTX_rand_key.

source

pub fn set_key_length(&mut self, len: usize) -> Result<(), ErrorStack>

Sets the length of the key expected by the context.

Only some ciphers support configurable key lengths.

§Panics

Panics if the context has not been initialized with a cipher.

This corresponds to EVP_CIPHER_CTX_set_key_length.

source

pub fn iv_length(&self) -> usize

Returns the length of the IV expected by this context.

Returns 0 if the cipher does not use an IV.

§Panics

Panics if the context has not been initialized with a cipher.

This corresponds to EVP_CIPHER_CTX_iv_length.

source

pub fn num(&self) -> usize

Returns the num parameter of the cipher.

Built-in ciphers typically use this to track how much of the current underlying block has been “used” already.

§Panics

Panics if the context has not been initialized with a cipher.

This corresponds to EVP_CIPHER_CTX_num.

source

pub fn set_iv_length(&mut self, len: usize) -> Result<(), ErrorStack>

Sets the length of the IV expected by this context.

Only some ciphers support configurable IV lengths.

§Panics

Panics if the context has not been initialized with a cipher.

This corresponds to EVP_CIPHER_CTX_ctrl.

source

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

Retrieves the calculated authentication tag from the context.

This should be called after Self::cipher_final, and is only supported by authenticated ciphers.

The size of the buffer indicates the size of the tag. While some ciphers support a range of tag sizes, it is recommended to pick the maximum size.

This corresponds to EVP_CIPHER_CTX_ctrl.

source

pub fn set_tag_length(&mut self, len: usize) -> Result<(), ErrorStack>

Sets the length of the generated authentication tag.

This must be called when encrypting with a cipher in CCM mode to use a tag size other than the default.

This corresponds to EVP_CIPHER_CTX_ctrl.

source

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

Sets the authentication tag for verification during decryption.

This corresponds to EVP_CIPHER_CTX_ctrl.

source

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

Enables or disables padding.

If padding is disabled, the plaintext must be an exact multiple of the cipher’s block size.

This corresponds to EVP_CIPHER_CTX_set_padding.

source

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

Sets the total length of plaintext data.

This is required for ciphers operating in CCM mode.

This corresponds to EVP_CipherUpdate.

source

pub fn set_flags(&mut self, flags: CipherCtxFlags)

Set ctx flags.

This function is currently used to enable AES key wrap feature supported by OpenSSL 1.0.2 or newer.

This corresponds to EVP_CIPHER_CTX_set_flags.

source

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

Writes data into the context.

Providing no output buffer will cause the input to be considered additional authenticated data (AAD).

Returns the number of bytes written to output.

§Panics

Panics if output doesn’t contain enough space for data to be written.

This corresponds to EVP_CipherUpdate.

source

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

Writes data into the context.

Providing no output buffer will cause the input to be considered additional authenticated data (AAD).

Returns the number of bytes written to output.

This function is the same as Self::cipher_update but with the output size check removed. It can be used when the exact buffer size control is maintained by the caller.

§Safety

The caller is expected to provide 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.

This corresponds to EVP_CipherUpdate.

source

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

Like Self::cipher_update except that it appends output to a Vec.

source

pub fn cipher_update_inplace( &mut self, data: &mut [u8], inlen: usize, ) -> Result<usize, ErrorStack>

Like Self::cipher_update except that it writes output into the data buffer. The inlen parameter specifies the number of bytes in data that are considered the input. For streaming ciphers, the size of data must be at least the input size. Otherwise, it must be at least an additional block size larger.

Note: Use Self::cipher_update with no output argument to write AAD.

§Panics

This function panics if the input size cannot be represented as int or exceeds the buffer size, or if the output buffer does not contain enough additional space.

This corresponds to EVP_CipherUpdate.

source

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

Finalizes the encryption or decryption process.

Any remaining data will be written to the output buffer.

Returns the number of bytes written to output.

§Panics

Panics if output is smaller than the cipher’s block size.

This corresponds to EVP_CipherFinal.

source

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

Finalizes the encryption or decryption process.

Any remaining data will be written to the output buffer.

Returns the number of bytes written to output.

This function is the same as Self::cipher_final but with the output buffer size check removed.

§Safety

The caller is expected to provide output buffer large enough to contain correct number of bytes. For streaming ciphers the output buffer can be empty, for block ciphers the output buffer should be at least as big as the block.

This corresponds to EVP_CipherFinal.

source