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
//! A cipher's own parameters with borrowed AEAD values.
use crate::;
use fmt;
/// A cipher's own parameters, a nonce and initial associated data, all
/// borrowed, and a tag size.
///
/// No allocation or copying, so it needs no `alloc` feature: GCM and EAX take
/// it without an allocator. A mode keeps the nonce, tag size and initial
/// associated data and initializes its cipher with the inner parameters alone,
/// so a cipher whose parameters are more than a key, such as RC2 with its
/// effective key bits, works under GCM, CCM, EAX, OCB and KCCM. GCM-SIV derives
/// its message keys from the key bytes and does not take it. `TParams` may be
/// unsized, such as a trait object. Nothing is validated until the mode is
/// initialized.
///
/// It does not implement `KeyParams`: a mode takes it through an
/// implementation of its own, which strips the AEAD values, rather than the
/// one over `KeyParams`, which hands the whole parameters to the cipher. The
/// engines that carry their own primitive take [`AeadParamsRef`](crate::AeadParamsRef)
/// instead.
///
/// The caller owns every value and is responsible for wiping it; dropping this
/// view modifies nothing. `Debug` prints the inner parameters as their type
/// does and only the lengths of the rest. `ParamsWithAeadOwned`, with the
/// `alloc` feature, owns them instead.
///
/// Constant time: no method inspects the nonce or associated data.
///
/// # Example
///
/// ```
/// use tc_aead_cipher::{AeadCipher, AeadCipherInit, EaxBlockCipher, ParamsWithAeadRef};
/// use tc_block_cipher::CipherDirection;
/// use tc_rc_cipher::{Rc2Engine, Rc2ParamsRef};
///
/// // RC2 with 40 effective key bits, under EAX, with no allocator
/// let (key, nonce) = ([0x42; 16], [0x24; 8]);
/// let rc2 = Rc2ParamsRef::with_effective_key_bits(&key, 40);
/// let params = ParamsWithAeadRef::new(&rc2, &nonce, 8, b"header");
/// let mut eax = EaxBlockCipher::new(Rc2Engine::new());
///
/// eax.init(CipherDirection::Encrypt, ¶ms)?;
/// let mut sealed = [0; 14 + 8];
/// let written = eax.process_bytes(b"attack at dawn", &mut sealed)?;
/// eax.do_final(&mut sealed[written..])?;
///
/// eax.init(CipherDirection::Decrypt, ¶ms)?;
/// let mut opened = [0; 14];
/// let written = eax.process_bytes(&sealed, &mut opened)?;
/// eax.do_final(&mut opened[written..])?;
/// assert_eq!(&opened, b"attack at dawn");
/// # Ok::<(), Box<dyn core::error::Error>>(())
/// ```