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.
FixedBufferedBlockCipherandBufferedBlockCipher(alloc) — atc_block_modesmode, buffered to whole blocks.FixedPaddedBufferedBlockCipherandPaddedBufferedBlockCipher(alloc) — the same with atc_block_paddingscheme, PKCS#7 by default.BufferedStreamCipher— atc_stream_cipherengine.BufferedAeadBlockCipherandBufferedAeadCipher— atc_aead_ciphermode over a block cipher, or an AEAD that carries its own primitive.FixedBufferedAsymmetricBlockCipherandBufferedAsymmetricBlockCipher(alloc) — atc_asym_cipherengine or encoding, such as RSA with PKCS#1 v1.5 or OAEP, taking its one block in pieces.
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, ¶ms)?;
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, ¶ms)?;
assert_eq!(seal(&mut chacha, message)?.len(), 14); // as long as the messageStructs§
- Buffered
Aead Block Cipher - Puts the AEAD mode
Cover a block cipher, such as GCM, behind theBufferedCipherinterface; Bouncy Castle’sBufferedAeadBlockCipher. Algorithms that carry their own primitive belong inBufferedAeadCipher. - Buffered
Aead Cipher - Puts the AEAD
Cbehind theBufferedCipherinterface, for an algorithm that carries its own primitive, such as Ascon; Bouncy Castle’sBufferedAeadCipher. Modes over a block cipher belong inBufferedAeadBlockCipher, which reports that cipher’s block size. - Buffered
Asymmetric Block Cipher - A buffering layer over the asymmetric block cipher
C, which sizes its buffer from the cipher atinit; Bouncy Castle’sBufferedAsymmetricBlockCipher. Available with theallocfeature. - Buffered
Block Cipher - An unpadded buffering layer over the block-cipher mode
C, which sizes its buffers from the mode at run time; Bouncy Castle’sBufferedBlockCipher. Available with theallocfeature. - Buffered
Stream Cipher - Puts the stream cipher
Cbehind theBufferedCipherinterface; Bouncy Castle’sBufferedStreamCipher. - Fixed
Buffered Asymmetric Block Cipher - A buffering layer over the asymmetric block cipher
Cwith an inline buffer ofNbytes, for builds without an allocator; Bouncy Castle’sBufferedAsymmetricBlockCipher. - Fixed
Buffered Block Cipher - An unpadded buffering layer over the block-cipher mode
Cwith blocks ofNbytes, kept inline for builds without an allocator; Bouncy Castle’sBufferedBlockCipher. - Fixed
Padded Buffered Block Cipher - A buffering layer over the block-cipher mode
Cwith blocks ofNbytes that pads the final block withP, PKCS#7 unless another scheme is given, and keeps its buffers inline for builds without an allocator; Bouncy Castle’sPaddedBufferedBlockCipher. - Padded
Buffered Block Cipher - A buffering layer over the block-cipher mode
Cthat pads the final block withP, PKCS#7 unless another scheme is given, and sizes its buffers from the mode at run time; Bouncy Castle’sPaddedBufferedBlockCipher. Available with theallocfeature.
Enums§
- Buffered
Error - A failure of a buffered adapter;
Eis the wrapped cipher’s processing error,Infalliblewhere there is none. - Cipher
Direction - The transformation direction selected during cipher initialization.
Traits§
- Buffered
Cipher - 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. - Buffered
Cipher Init - Prepares a
BufferedCipherfrom a parameter value of typeP.