Skip to main content

Crate tc_buffered_cipher

Crate tc_buffered_cipher 

Source
Expand description

One buffered interface over block modes with or without padding, stream ciphers, AEADs and asymmetric block ciphers: the BufferedCipher and BufferedCipherInit contracts, the Rust form of Bouncy Castle’s IBufferedCipher, and the adapters that put each family behind them.

Every adapter takes input in pieces of any size, holds back what its cipher cannot process yet and finishes in do_final; the sizing methods say how much each call writes. CipherDirection converts to and from the block-cipher, stream-cipher and asymmetric-block-cipher contracts’ own directions. BufferedError carries the failures of the block, stream and asymmetric adapters, while the AEAD adapters report their engine’s error.

The crate is no_std and contains no unsafe code. The default-off alloc feature adds the adapters that size their buffers from the mode or the key at run time; the Fixed forms keep theirs inline.

Every adapter documents its timing: each is constant time exactly when the cipher it wraps is, and lengths are public. Padded decryption needs care: the length it writes and a CorruptPadding error reveal the padding, which is a padding oracle, so authenticate CBC ciphertext before decrypting it, or use an AEAD.

§Example

Generic code drives every family through the same calls:

use tc_aes::AesEngine;
use tc_block_modes::FixedCbcBlockCipher;
use tc_buffered_cipher::{
    BufferedCipher, BufferedCipherInit, BufferedStreamCipher, CipherDirection,
    FixedPaddedBufferedBlockCipher,
};
use tc_chacha::ChaCha7539Engine;

fn seal<C: BufferedCipher>(cipher: &mut C, message: &[u8]) -> Result<Vec<u8>, C::Error> {
    let mut sealed = vec![0; cipher.output_len(message.len())?];
    let mut written = cipher.process_bytes(message, &mut sealed)?;
    written += cipher.do_final(&mut sealed[written..])?;
    sealed.truncate(written);
    Ok(sealed)
}

let message = b"attack at dawn";

let mode = FixedCbcBlockCipher::<_, 16>::new(AesEngine::new());
let mut cbc = FixedPaddedBufferedBlockCipher::<_, 16>::new(mode);
let params = tc_block_modes::KeyWithIvRef::new(&[0x42; 16], &[0x24; 16]);
cbc.init(CipherDirection::Encrypt, &params)?;
assert_eq!(seal(&mut cbc, message)?.len(), 16); // padded to a whole block

let mut chacha = BufferedStreamCipher::new(ChaCha7539Engine::new());
let params = tc_stream_cipher::KeyWithIvRef::new(&[0x42; 32], &[0x24; 12]);
chacha.init(CipherDirection::Encrypt, &params)?;
assert_eq!(seal(&mut chacha, message)?.len(), 14); // as long as the message

Structs§

BufferedAeadBlockCipher
Puts the AEAD mode C over a block cipher, such as GCM, behind the BufferedCipher interface; Bouncy Castle’s BufferedAeadBlockCipher. Algorithms that carry their own primitive belong in BufferedAeadCipher.
BufferedAeadCipher
Puts the AEAD C behind the BufferedCipher interface, for an algorithm that carries its own primitive, such as Ascon; Bouncy Castle’s BufferedAeadCipher. Modes over a block cipher belong in BufferedAeadBlockCipher, which reports that cipher’s block size.
BufferedAsymmetricBlockCipher
A buffering layer over the asymmetric block cipher C, which sizes its buffer from the cipher at init; Bouncy Castle’s BufferedAsymmetricBlockCipher. Available with the alloc feature.
BufferedBlockCipher
An unpadded buffering layer over the block-cipher mode C, which sizes its buffers from the mode at run time; Bouncy Castle’s BufferedBlockCipher. Available with the alloc feature.
BufferedStreamCipher
Puts the stream cipher C behind the BufferedCipher interface; Bouncy Castle’s BufferedStreamCipher.
FixedBufferedAsymmetricBlockCipher
A buffering layer over the asymmetric block cipher C with an inline buffer of N bytes, for builds without an allocator; Bouncy Castle’s BufferedAsymmetricBlockCipher.
FixedBufferedBlockCipher
An unpadded buffering layer over the block-cipher mode C with blocks of N bytes, kept inline for builds without an allocator; Bouncy Castle’s BufferedBlockCipher.
FixedPaddedBufferedBlockCipher
A buffering layer over the block-cipher mode C with blocks of N bytes that pads the final block with P, PKCS#7 unless another scheme is given, and keeps its buffers inline for builds without an allocator; Bouncy Castle’s PaddedBufferedBlockCipher.
PaddedBufferedBlockCipher
A buffering layer over the block-cipher mode C that pads the final block with P, PKCS#7 unless another scheme is given, and sizes its buffers from the mode at run time; Bouncy Castle’s PaddedBufferedBlockCipher. Available with the alloc feature.

Enums§

BufferedError
A failure of a buffered adapter; E is the wrapped cipher’s processing error, Infallible where there is none.
CipherDirection
The transformation direction selected during cipher initialization.

Traits§

BufferedCipher
A cipher that takes input in pieces of any size and finishes in do_final, whatever its family: a block-cipher mode with or without padding, a stream cipher or an AEAD.
BufferedCipherInit
Prepares a BufferedCipher from a parameter value of type P.