Skip to main content

Crate tc_stream_cipher

Crate tc_stream_cipher 

Source
Expand description

Shared interfaces and key and IV containers for stream ciphers.

This crate defines how to initialize a stream cipher and apply its keystream; it does not implement an encryption algorithm or authentication. Use a concrete engine with these traits, and an authenticated-encryption construction when protecting messages.

§Using an engine

Supply the key through KeyParams and, for ciphers that take one, the IV (nonce) through IvParams, select a CipherDirection, and call StreamCipherInit::init. After successful initialization, StreamCipher::process_bytes transforms a slice and StreamCipher::return_byte a single byte, both advancing the keystream, and StreamCipher::reset returns to its start. Supported key and IV lengths, round counts, keystream limits, timing guarantees and state after a rejected initialization are defined by the concrete engine.

§Implementing an engine

An engine implements StreamCipherInit for the parameters it accepts and StreamCipher for processing. The toy engine below repeats a four-byte key XORed with a four-byte IV as its keystream; it shows the contract and is not a cipher.

use tc_stream_cipher::{
    CipherDirection, InitError, IvParams, KeyParams, KeyWithIvFixed, KeyWithIvRef,
    StreamCipher, StreamCipherInit, StreamError,
};

struct Xor4 {
    pad: Option<[u8; 4]>,
    position: usize,
}

impl<P: KeyParams + IvParams + ?Sized> StreamCipherInit<P> for Xor4 {
    type Error = InitError;

    fn init(&mut self, _direction: CipherDirection, params: &P) -> Result<(), InitError> {
        let (key, iv) = (params.key(), params.iv());
        let key: [u8; 4] = key.try_into().map_err(|_| InitError::InvalidKeyLength(key.len()))?;
        let iv: [u8; 4] = iv.try_into().map_err(|_| InitError::InvalidIvLength(iv.len()))?;
        self.pad = Some(core::array::from_fn(|index| key[index] ^ iv[index]));
        self.position = 0;
        Ok(())
    }
}

impl StreamCipher for Xor4 {
    type Error = StreamError;

    fn return_byte(&mut self, input: u8) -> Result<u8, StreamError> {
        let mut output = [0];
        self.process_bytes(&[input], &mut output)?;
        Ok(output[0])
    }

    fn process_bytes(&mut self, input: &[u8], output: &mut [u8]) -> Result<usize, StreamError> {
        let pad = self.pad.ok_or(StreamError::NotInitialised)?;
        let output = output.get_mut(..input.len()).ok_or(StreamError::BufferTooShort)?;
        for (out, byte) in output.iter_mut().zip(input) {
            *out = byte ^ pad[self.position % 4];
            self.position += 1;
        }
        Ok(input.len())
    }

    fn reset(&mut self) {
        self.position = 0;
    }
}

let mut engine = Xor4 { pad: None, position: 0 };
assert_eq!(engine.return_byte(0), Err(StreamError::NotInitialised));

let params = KeyWithIvFixed::new([0xf0; 4], [0x0f, 0x0f, 0x0f, 0x0e]);
engine.init(CipherDirection::Encrypt, &params)?;
let mut ciphertext = [0; 5];
assert_eq!(engine.process_bytes(b"hello", &mut ciphertext)?, 5);
assert_eq!(ciphertext, [0x97, 0x9a, 0x93, 0x92, 0x90]);

engine.init(CipherDirection::Decrypt, &params)?;
let mut plaintext = [0; 5];
engine.process_bytes(&ciphertext, &mut plaintext)?;
assert_eq!(&plaintext, b"hello");

let short_iv = [0; 3];
assert_eq!(
    engine.init(CipherDirection::Encrypt, &KeyWithIvRef::new(&[0; 4], &short_iv)),
    Err(InitError::InvalidIvLength(3))
);

§Choosing parameter storage

  • KeyRef and KeyWithIvRef borrow existing bytes without copying or wiping them.
  • KeyFixed and KeyWithIvFixed own fixed-size arrays and wipe them on drop.
  • KeyOwned and KeyWithIvOwned, available with the alloc feature, take ownership of byte vectors and wipe them on drop.

The key-only containers serve ciphers that take no IV, such as RC4. None of the containers validates algorithm-specific lengths. Wiping an owned container does not erase caller-held copies, engine state or every temporary copy. Callers must manage those lifetimes separately.

§Features

The crate is no_std and requires no allocator by default. Enable alloc for KeyOwned and KeyWithIvOwned; this does not require the standard library.

InitError and StreamError are reusable error types. The traits use associated error types so an engine may expose more specific failures.

Structs§

KeyFixed
An owned, fixed-size key array that is wiped on drop.
KeyOwned
An owned key vector that is wiped on drop.
KeyRef
A borrowed key slice with no allocation or copying.
KeyWithIvFixed
An owned, fixed-size key and IV (nonce), both wiped on drop.
KeyWithIvOwned
An owned key vector and IV (nonce) vector, both wiped on drop.
KeyWithIvRef
A borrowed key and IV (nonce) with no allocation or copying.

Enums§

CipherDirection
The transformation direction selected during cipher initialization.
InitError
Failures common to cipher initialization.
StreamError
Failures shared by stream-cipher implementations.

Traits§

IvParams
Provides borrowed access to initialization-vector (nonce) bytes.
KeyParams
Provides borrowed access to cipher key bytes.
StreamCipher
An initialized symmetric-key stream cipher.
StreamCipherInit
Initializes an object from parameters of type P.