1 | //! Common cryptographic traits. |
2 | |
3 | #![no_std ] |
4 | #![cfg_attr (docsrs, feature(doc_cfg))] |
5 | #![doc ( |
6 | html_logo_url = "https://raw.githubusercontent.com/RustCrypto/media/6ee8e381/logo.svg" , |
7 | html_favicon_url = "https://raw.githubusercontent.com/RustCrypto/media/6ee8e381/logo.svg" |
8 | )] |
9 | #![forbid (unsafe_code)] |
10 | #![warn (missing_docs, rust_2018_idioms)] |
11 | |
12 | #[cfg (feature = "std" )] |
13 | extern crate std; |
14 | |
15 | #[cfg (feature = "rand_core" )] |
16 | pub use rand_core; |
17 | |
18 | pub use generic_array; |
19 | pub use generic_array::typenum; |
20 | |
21 | use core::fmt; |
22 | use generic_array::{typenum::Unsigned, ArrayLength, GenericArray}; |
23 | #[cfg (feature = "rand_core" )] |
24 | use rand_core::{CryptoRng, RngCore}; |
25 | |
26 | /// Block on which [`BlockSizeUser`] implementors operate. |
27 | pub type Block<B> = GenericArray<u8, <B as BlockSizeUser>::BlockSize>; |
28 | |
29 | /// Parallel blocks on which [`ParBlocksSizeUser`] implementors operate. |
30 | pub type ParBlocks<T> = GenericArray<Block<T>, <T as ParBlocksSizeUser>::ParBlocksSize>; |
31 | |
32 | /// Output array of [`OutputSizeUser`] implementors. |
33 | pub type Output<T> = GenericArray<u8, <T as OutputSizeUser>::OutputSize>; |
34 | |
35 | /// Key used by [`KeySizeUser`] implementors. |
36 | pub type Key<B> = GenericArray<u8, <B as KeySizeUser>::KeySize>; |
37 | |
38 | /// Initialization vector (nonce) used by [`IvSizeUser`] implementors. |
39 | pub type Iv<B> = GenericArray<u8, <B as IvSizeUser>::IvSize>; |
40 | |
41 | /// Types which process data in blocks. |
42 | pub trait BlockSizeUser { |
43 | /// Size of the block in bytes. |
44 | type BlockSize: ArrayLength<u8> + 'static; |
45 | |
46 | /// Return block size in bytes. |
47 | fn block_size() -> usize { |
48 | Self::BlockSize::USIZE |
49 | } |
50 | } |
51 | |
52 | impl<T: BlockSizeUser> BlockSizeUser for &T { |
53 | type BlockSize = T::BlockSize; |
54 | } |
55 | |
56 | impl<T: BlockSizeUser> BlockSizeUser for &mut T { |
57 | type BlockSize = T::BlockSize; |
58 | } |
59 | |
60 | /// Types which can process blocks in parallel. |
61 | pub trait ParBlocksSizeUser: BlockSizeUser { |
62 | /// Number of blocks which can be processed in parallel. |
63 | type ParBlocksSize: ArrayLength<Block<Self>>; |
64 | } |
65 | |
66 | /// Types which return data with the given size. |
67 | pub trait OutputSizeUser { |
68 | /// Size of the output in bytes. |
69 | type OutputSize: ArrayLength<u8> + 'static; |
70 | |
71 | /// Return output size in bytes. |
72 | fn output_size() -> usize { |
73 | Self::OutputSize::USIZE |
74 | } |
75 | } |
76 | |
77 | /// Types which use key for initialization. |
78 | /// |
79 | /// Generally it's used indirectly via [`KeyInit`] or [`KeyIvInit`]. |
80 | pub trait KeySizeUser { |
81 | /// Key size in bytes. |
82 | type KeySize: ArrayLength<u8> + 'static; |
83 | |
84 | /// Return key size in bytes. |
85 | fn key_size() -> usize { |
86 | Self::KeySize::USIZE |
87 | } |
88 | } |
89 | |
90 | /// Types which use initialization vector (nonce) for initialization. |
91 | /// |
92 | /// Generally it's used indirectly via [`KeyIvInit`] or [`InnerIvInit`]. |
93 | pub trait IvSizeUser { |
94 | /// Initialization vector size in bytes. |
95 | type IvSize: ArrayLength<u8> + 'static; |
96 | |
97 | /// Return IV size in bytes. |
98 | fn iv_size() -> usize { |
99 | Self::IvSize::USIZE |
100 | } |
101 | } |
102 | |
103 | /// Types which use another type for initialization. |
104 | /// |
105 | /// Generally it's used indirectly via [`InnerInit`] or [`InnerIvInit`]. |
106 | pub trait InnerUser { |
107 | /// Inner type. |
108 | type Inner; |
109 | } |
110 | |
111 | /// Resettable types. |
112 | pub trait Reset { |
113 | /// Reset state to its initial value. |
114 | fn reset(&mut self); |
115 | } |
116 | |
117 | /// Trait which stores algorithm name constant, used in `Debug` implementations. |
118 | pub trait AlgorithmName { |
119 | /// Write algorithm name into `f`. |
120 | fn write_alg_name(f: &mut fmt::Formatter<'_>) -> fmt::Result; |
121 | } |
122 | |
123 | /// Types which can be initialized from key. |
124 | pub trait KeyInit: KeySizeUser + Sized { |
125 | /// Create new value from fixed size key. |
126 | fn new(key: &Key<Self>) -> Self; |
127 | |
128 | /// Create new value from variable size key. |
129 | fn new_from_slice(key: &[u8]) -> Result<Self, InvalidLength> { |
130 | if key.len() != Self::KeySize::to_usize() { |
131 | Err(InvalidLength) |
132 | } else { |
133 | Ok(Self::new(key:Key::<Self>::from_slice(key))) |
134 | } |
135 | } |
136 | |
137 | /// Generate random key using the provided [`CryptoRng`]. |
138 | #[cfg (feature = "rand_core" )] |
139 | #[cfg_attr (docsrs, doc(cfg(feature = "rand_core" )))] |
140 | #[inline ] |
141 | fn generate_key(mut rng: impl CryptoRng + RngCore) -> Key<Self> { |
142 | let mut key = Key::<Self>::default(); |
143 | rng.fill_bytes(&mut key); |
144 | key |
145 | } |
146 | } |
147 | |
148 | /// Types which can be initialized from key and initialization vector (nonce). |
149 | pub trait KeyIvInit: KeySizeUser + IvSizeUser + Sized { |
150 | /// Create new value from fixed length key and nonce. |
151 | fn new(key: &Key<Self>, iv: &Iv<Self>) -> Self; |
152 | |
153 | /// Create new value from variable length key and nonce. |
154 | #[inline ] |
155 | fn new_from_slices(key: &[u8], iv: &[u8]) -> Result<Self, InvalidLength> { |
156 | let key_len = Self::KeySize::USIZE; |
157 | let iv_len = Self::IvSize::USIZE; |
158 | if key.len() != key_len || iv.len() != iv_len { |
159 | Err(InvalidLength) |
160 | } else { |
161 | Ok(Self::new( |
162 | Key::<Self>::from_slice(key), |
163 | Iv::<Self>::from_slice(iv), |
164 | )) |
165 | } |
166 | } |
167 | |
168 | /// Generate random key using the provided [`CryptoRng`]. |
169 | #[cfg (feature = "rand_core" )] |
170 | #[cfg_attr (docsrs, doc(cfg(feature = "rand_core" )))] |
171 | #[inline ] |
172 | fn generate_key(mut rng: impl CryptoRng + RngCore) -> Key<Self> { |
173 | let mut key = Key::<Self>::default(); |
174 | rng.fill_bytes(&mut key); |
175 | key |
176 | } |
177 | |
178 | /// Generate random IV using the provided [`CryptoRng`]. |
179 | #[cfg (feature = "rand_core" )] |
180 | #[cfg_attr (docsrs, doc(cfg(feature = "rand_core" )))] |
181 | #[inline ] |
182 | fn generate_iv(mut rng: impl CryptoRng + RngCore) -> Iv<Self> { |
183 | let mut iv = Iv::<Self>::default(); |
184 | rng.fill_bytes(&mut iv); |
185 | iv |
186 | } |
187 | |
188 | /// Generate random key and nonce using the provided [`CryptoRng`]. |
189 | #[cfg (feature = "rand_core" )] |
190 | #[cfg_attr (docsrs, doc(cfg(feature = "rand_core" )))] |
191 | #[inline ] |
192 | fn generate_key_iv(mut rng: impl CryptoRng + RngCore) -> (Key<Self>, Iv<Self>) { |
193 | (Self::generate_key(&mut rng), Self::generate_iv(&mut rng)) |
194 | } |
195 | } |
196 | |
197 | /// Types which can be initialized from another type (usually block ciphers). |
198 | /// |
199 | /// Usually used for initializing types from block ciphers. |
200 | pub trait InnerInit: InnerUser + Sized { |
201 | /// Initialize value from the `inner`. |
202 | fn inner_init(inner: Self::Inner) -> Self; |
203 | } |
204 | |
205 | /// Types which can be initialized from another type and additional initialization |
206 | /// vector/nonce. |
207 | /// |
208 | /// Usually used for initializing types from block ciphers. |
209 | pub trait InnerIvInit: InnerUser + IvSizeUser + Sized { |
210 | /// Initialize value using `inner` and `iv` array. |
211 | fn inner_iv_init(inner: Self::Inner, iv: &Iv<Self>) -> Self; |
212 | |
213 | /// Initialize value using `inner` and `iv` slice. |
214 | fn inner_iv_slice_init(inner: Self::Inner, iv: &[u8]) -> Result<Self, InvalidLength> { |
215 | if iv.len() != Self::IvSize::to_usize() { |
216 | Err(InvalidLength) |
217 | } else { |
218 | Ok(Self::inner_iv_init(inner, iv:Iv::<Self>::from_slice(iv))) |
219 | } |
220 | } |
221 | |
222 | /// Generate random IV using the provided [`CryptoRng`]. |
223 | #[cfg (feature = "rand_core" )] |
224 | #[cfg_attr (docsrs, doc(cfg(feature = "rand_core" )))] |
225 | #[inline ] |
226 | fn generate_iv(mut rng: impl CryptoRng + RngCore) -> Iv<Self> { |
227 | let mut iv = Iv::<Self>::default(); |
228 | rng.fill_bytes(&mut iv); |
229 | iv |
230 | } |
231 | } |
232 | |
233 | impl<T> KeySizeUser for T |
234 | where |
235 | T: InnerUser, |
236 | T::Inner: KeySizeUser, |
237 | { |
238 | type KeySize = <T::Inner as KeySizeUser>::KeySize; |
239 | } |
240 | |
241 | impl<T> KeyIvInit for T |
242 | where |
243 | T: InnerIvInit, |
244 | T::Inner: KeyInit, |
245 | { |
246 | #[inline ] |
247 | fn new(key: &Key<Self>, iv: &Iv<Self>) -> Self { |
248 | Self::inner_iv_init(T::Inner::new(key), iv) |
249 | } |
250 | |
251 | #[inline ] |
252 | fn new_from_slices(key: &[u8], iv: &[u8]) -> Result<Self, InvalidLength> { |
253 | T::Inner::new_from_slice(key).and_then(|i: ::Inner| T::inner_iv_slice_init(inner:i, iv)) |
254 | } |
255 | } |
256 | |
257 | impl<T> KeyInit for T |
258 | where |
259 | T: InnerInit, |
260 | T::Inner: KeyInit, |
261 | { |
262 | #[inline ] |
263 | fn new(key: &Key<Self>) -> Self { |
264 | Self::inner_init(T::Inner::new(key)) |
265 | } |
266 | |
267 | #[inline ] |
268 | fn new_from_slice(key: &[u8]) -> Result<Self, InvalidLength> { |
269 | T::Inner::new_from_slice(key) |
270 | .map_err(|_| InvalidLength) |
271 | .map(Self::inner_init) |
272 | } |
273 | } |
274 | |
275 | // Unfortunately this blanket impl is impossible without mutually |
276 | // exclusive traits, see: https://github.com/rust-lang/rfcs/issues/1053 |
277 | // or at the very least without: https://github.com/rust-lang/rust/issues/20400 |
278 | /* |
279 | impl<T> KeyIvInit for T |
280 | where |
281 | T: InnerInit, |
282 | T::Inner: KeyIvInit, |
283 | { |
284 | #[inline] |
285 | fn new(key: &Key<Self>, iv: &Iv<Self>) -> Self { |
286 | Self::inner_init(T::Inner::new(key, iv)) |
287 | } |
288 | |
289 | #[inline] |
290 | fn new_from_slices(key: &[u8], iv: &[u8]) -> Result<Self, InvalidLength> { |
291 | T::Inner::new_from_slice(key) |
292 | .map_err(|_| InvalidLength) |
293 | .map(Self::inner_init) |
294 | } |
295 | } |
296 | */ |
297 | |
298 | /// The error type returned when key and/or IV used in the [`KeyInit`], |
299 | /// [`KeyIvInit`], and [`InnerIvInit`] slice-based methods had |
300 | /// an invalid length. |
301 | #[derive (Copy, Clone, Eq, PartialEq, Debug)] |
302 | pub struct InvalidLength; |
303 | |
304 | impl fmt::Display for InvalidLength { |
305 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> Result<(), fmt::Error> { |
306 | f.write_str(data:"Invalid Length" ) |
307 | } |
308 | } |
309 | |
310 | #[cfg (feature = "std" )] |
311 | impl std::error::Error for InvalidLength {} |
312 | |