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
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
//! 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, ¶ms)?;
//! 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, ¶ms)?;
//! 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))
//! );
//! # Ok::<(), Box<dyn core::error::Error>>(())
//! ```
//!
//! # 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.
//!
extern crate alloc;
pub use CipherDirection;
pub use InitError;
pub use ;
pub use ;
pub use StreamError;
pub use ;