Trait StreamCipher 

pub trait StreamCipher {
    // Required methods
    fn check_remaining(&self, data_len: usize) -> Result<(), StreamCipherError>;
    fn unchecked_apply_keystream_inout(&mut self, buf: InOutBuf<'_, '_, u8>);
    fn unchecked_write_keystream(&mut self, buf: &mut [u8]);

    // Provided methods
    fn unchecked_apply_keystream(&mut self, buf: &mut [u8]) { ... }
    fn unchecked_apply_keystream_b2b(
        &mut self,
        input: &[u8],
        output: &mut [u8],
    ) -> Result<(), NotEqualError> { ... }
    fn try_apply_keystream_inout(
        &mut self,
        buf: InOutBuf<'_, '_, u8>,
    ) -> Result<(), StreamCipherError> { ... }
    fn try_apply_keystream(
        &mut self,
        buf: &mut [u8],
    ) -> Result<(), StreamCipherError> { ... }
    fn try_apply_keystream_b2b(
        &mut self,
        input: &[u8],
        output: &mut [u8],
    ) -> Result<(), StreamCipherError> { ... }
    fn try_write_keystream(
        &mut self,
        buf: &mut [u8],
    ) -> Result<(), StreamCipherError> { ... }
    fn apply_keystream_inout(&mut self, buf: InOutBuf<'_, '_, u8>) { ... }
    fn apply_keystream(&mut self, buf: &mut [u8]) { ... }
    fn apply_keystream_b2b(&mut self, input: &[u8], output: &mut [u8]) { ... }
    fn write_keystream(&mut self, buf: &mut [u8]) { ... }
}

Stream cipher trait.

This trait applies only to synchronous stream ciphers, which generate a keystream and XOR data with it during both encryption and decryption. Therefore, instead of separate methods for encryption and decryption, this trait provides methods for keystream application.

Notes on Keystream Repetition

All stream ciphers have a finite state, so the generated keystream inevitably repeats itself, making the cipher vulnerable to chosen plaintext attack. Typically, the repetition period is astronomically large, rendering keystream repetition impossible to encounter in practice.

However, counter-based stream ciphers allow seeking across the keystream, and some also use small counters (e.g. 32 bits). This can result in triggering keystream repetition in practice.

To guard against this, methods either panic (e.g. StreamCipher::apply_keystream) or return StreamCipherError (e.g. StreamCipher::try_apply_keystream) when keystream repetition occurs. We also provide a number of “unchecked” methods (e.g. StreamCipher::unchecked_apply_keystream), but they should be used with extreme care.

For efficiency reasons, the check for keystream repetition is typically implemented by forbidding the generation of the last keystream block in both the keystream application methods and the seeking methods defined in the StreamCipherSeek trait.

Required Methods

fn check_remaining(&self, data_len: usize) -> Result<(), StreamCipherError>

Check that the cipher can generate a keystream with a length of data_len bytes.

Errors

Returns StreamCipherError in the event it cannot.

fn unchecked_apply_keystream_inout(&mut self, buf: InOutBuf<'_, '_, u8>)

Apply keystream to inout without checking for keystream repetition.

WARNING

This method should be used with extreme caution! Triggering keystream repetition can expose the stream cipher to chosen plaintext attacks.

fn unchecked_write_keystream(&mut self, buf: &mut [u8])

Apply keystream to buf without checking for keystream repetition.

WARNING

This method should be used with extreme caution! Triggering keystream repetition can expose the stream cipher to chosen plaintext attacks.

Provided Methods

fn unchecked_apply_keystream(&mut self, buf: &mut [u8])

Apply keystream to data behind buf without checking for keystream repetition.

WARNING

This method should be used with extreme caution! Triggering keystream repetition can expose the stream cipher to chosen plaintext attacks.

fn unchecked_apply_keystream_b2b( &mut self, input: &[u8], output: &mut [u8], ) -> Result<(), NotEqualError>

Apply keystream to data buffer-to-buffer without checking for keystream repetition.

It will XOR generated keystream with data from the input buffer and will write result to the output buffer.

Errors

Returns NotEqualError if the input and output buffers have different lengths.

WARNING

This method should be used with extreme caution! Triggering keystream repetition can expose the stream cipher to chosen plaintext attacks.

fn try_apply_keystream_inout( &mut self, buf: InOutBuf<'_, '_, u8>, ) -> Result<(), StreamCipherError>

Apply keystream to inout data.

Errors

If the end of the keystream is reached with the given buffer length, the method will return StreamCipherError without modifying buf.

fn try_apply_keystream( &mut self, buf: &mut [u8], ) -> Result<(), StreamCipherError>

Apply keystream to data behind buf.

Errors

If the end of the keystream is reached with the given buffer length, the method will return StreamCipherError without modifying buf.

fn try_apply_keystream_b2b( &mut self, input: &[u8], output: &mut [u8], ) -> Result<(), StreamCipherError>

Apply keystream to data buffer-to-buffer.

It will XOR generated keystream with data from the input buffer and will write result to the output buffer.

Errors

Returns StreamCipherError without modifying the buffers if the input and output buffers have different lengths, or if the end of the keystream is reached with the given data length.

fn try_write_keystream( &mut self, buf: &mut [u8], ) -> Result<(), StreamCipherError>

Write keystream to buf.

Errors

If the end of the keystream is reached with the given buffer length, the method will return StreamCipherError without modifying buf.

fn apply_keystream_inout(&mut self, buf: InOutBuf<'_, '_, u8>)

Apply keystream to inout data.

It will XOR generated keystream with the data behind in pointer and will write result to out pointer.

Panics

If the end of the keystream is reached with the given buffer length.

fn apply_keystream(&mut self, buf: &mut [u8])

Apply keystream to data in-place.

It will XOR generated keystream with data and will write result to the same buffer.

Panics

If the end of the keystream is reached with the given buffer length.

fn apply_keystream_b2b(&mut self, input: &[u8], output: &mut [u8])

Apply keystream to data buffer-to-buffer.

It will XOR generated keystream with data from the input buffer and will write result to the output buffer.

Panics

If the end of the keystream is reached with the given buffer length, of if the input and output buffers have different lengths.

fn write_keystream(&mut self, buf: &mut [u8])

Write keystream to buf.

Panics

If the end of the keystream is reached with the given buffer length.

Implementations on Foreign Types

impl<C: StreamCipher> StreamCipher for &mut C

fn check_remaining(&self, data_len: usize) -> Result<(), StreamCipherError>

fn unchecked_apply_keystream_inout(&mut self, buf: InOutBuf<'_, '_, u8>)

fn unchecked_write_keystream(&mut self, buf: &mut [u8])

Implementors

impl<T> StreamCipher for StreamCipherCoreWrapper<T>

where T: StreamCipherCore, T::BlockSize: BlockSizes,