1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
//! 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.
//!
//! - [`FixedBufferedBlockCipher`] and `BufferedBlockCipher` (`alloc`) — a
//! `tc_block_modes` mode, buffered to whole blocks.
//! - [`FixedPaddedBufferedBlockCipher`] and `PaddedBufferedBlockCipher`
//! (`alloc`) — the same with a `tc_block_padding` scheme, PKCS#7 by default.
//! - [`BufferedStreamCipher`] — a `tc_stream_cipher` engine.
//! - [`BufferedAeadBlockCipher`] and [`BufferedAeadCipher`] — a
//! `tc_aead_cipher` mode over a block cipher, or an AEAD that carries its own
//! primitive.
//! - [`FixedBufferedAsymmetricBlockCipher`] and `BufferedAsymmetricBlockCipher`
//! (`alloc`) — a `tc_asym_cipher` engine 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 message
//! # Ok::<(), Box<dyn core::error::Error>>(())
//! ```
extern crate alloc;
pub use BufferedAeadBlockCipher;
pub use BufferedAeadCipher;
pub use BufferedAsymmetricBlockCipher;
pub use FixedBufferedAsymmetricBlockCipher;
pub use BufferedBlockCipher;
pub use FixedBufferedBlockCipher;
pub use FixedPaddedBufferedBlockCipher;
pub use PaddedBufferedBlockCipher;
pub use CipherDirection;
pub use BufferedError;
pub use BufferedStreamCipher;
pub use BufferedCipher;
pub use BufferedCipherInit;