Struct openssl::cipher_ctx::CipherCtxRef

pub struct CipherCtxRef(_);

A reference to a CipherCtx.

Implementations

impl CipherCtxRef

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.

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.

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.

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.

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.

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.

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.

This corresponds to EVP_CIPHER_CTX_rand_key.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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 as specified by [Self::minimal_output_size].

This corresponds to EVP_CipherUpdate.

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.

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.

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.

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.

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.

pub fn cipher_final_vec(
    &mut self,
    output: &mut Vec<u8>
) -> Result<usize, ErrorStack>

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

Trait Implementations

impl AsRef<CipherCtxRef> for CipherCtx

fn as_ref(&self) -> &CipherCtxRef

Converts this type into a shared reference of the (usually inferred) input type.

impl Borrow<CipherCtxRef> for CipherCtx

fn borrow(&self) -> &CipherCtxRef

Immutably borrows from an owned value.

impl ForeignTypeRef for CipherCtxRef

type CType = EVP_CIPHER_CTX

The raw C type.

unsafe fn from_ptr<'a>(ptr: *mut Self::CType) -> &'a Self

Constructs a shared instance of this type from its raw type.

unsafe fn from_ptr_mut<'a>(ptr: *mut Self::CType) -> &'a mut Self

Constructs a mutable reference of this type from its raw type.

fn as_ptr(&self) -> *mut Self::CType

Returns a raw pointer to the wrapped value.

impl Send for CipherCtxRef

impl Sync for CipherCtxRef