embedded_cal/
hmac.rs

1// SPDX-License-Identifier: MIT OR Apache-2.0
2// SPDX-FileCopyrightText: Inria-AIO, Cryspen, and Christian Amsüss
3
4/// Message authentication based on hashes.
5pub trait HmacProvider {
6    type Algorithm: HmacAlgorithm;
7    /// A nascent state that has only received a key as input.
8    type Key: Clone + Sized;
9    /// State carried between rounds of feeding data into the HMAC.
10    type State: Sized;
11    /// Output of an HMAC operation.
12    type Output: AsRef<[u8]>;
13
14    /// Starts an HMAC operation based on a key that is entered as raw bytes.
15    ///
16    /// This is a convenience wrapper for `Self::init(Self::load_from_keydatra(algorithm, key))`.
17    fn init_with_keydata(&mut self, algorithm: Self::Algorithm, key: &[u8]) -> Self::State {
18        let key = self.load_from_keydata(algorithm, key);
19        self.init(key)
20    }
21    /// Initializes a key from raw bytes.
22    fn load_from_keydata(&mut self, algorithm: Self::Algorithm, key: &[u8]) -> Self::Key;
23    /// Starts an HMAC operation.
24    fn init(&mut self, key: Self::Key) -> Self::State;
25    fn update(&mut self, state: &mut Self::State, data: &[u8]);
26    fn finalize(&mut self, state: Self::State) -> Self::Output;
27
28    /// Compute HMAC over contiguous in-memory data in a single pass, based on a key directly
29    /// entered as bytes.
30    ///
31    /// This is a shortcut for [`self.init_with_keydata(…)`][Self::init_with_keydata()] /
32    /// [`self.update(…)`][Self::update()] / [`self.finalize(…)`][Self::finalize()].
33    fn hmac_with_keydata(
34        &mut self,
35        algorithm: Self::Algorithm,
36        key: &[u8],
37        data: &[u8],
38    ) -> Self::Output {
39        let mut state = self.init_with_keydata(algorithm, key);
40        self.update(&mut state, data);
41        self.finalize(state)
42    }
43}
44
45/// An HMAC algorithm identifier.
46#[allow(
47    clippy::len_without_is_empty,
48    reason = "Lint only makes sense when length can reasonably be zero, which is not the case here."
49)]
50pub trait HmacAlgorithm: Sized + PartialEq + Eq + core::fmt::Debug + Clone {
51    /// The maximum output of [`Self::len()`].
52    ///
53    /// This can be used by consumers of this trait (e.g. the HMAC trait) to build internal
54    /// buffers.
55    const MAX_LEN: usize;
56
57    /// A `[u8; MAX_LEN]` type.
58    ///
59    /// This is needed as a workaround while limitation inconst generics mean that users (in
60    /// particular, HKDF implementations) can not create a local variable of type `[u8;
61    /// Self::HmacAlgorithm::MAX_LEN]`.
62    ///
63    /// The only sensible implementation is `[u8; MAX_LEN]`. Users of the trait may panic if it is
64    /// not, but must assume that it is anything for safety and security.
65    type MaxLenBuf: AsMut<[u8]> + Sized + Default;
66
67    /// Output length in bytes.
68    ///
69    /// ## Constraints
70    ///
71    /// The returned value must not be greater than [`Self::MAX_LEN`]; otherwise, consumers of the
72    /// trait may panic.
73    fn len(&self) -> usize;
74
75    /// Selects an HMAC algorithm from its COSE number.
76    ///
77    /// The algorithm number comes from the ["COSE Algorithms"
78    /// registry](https://www.iana.org/assignments/cose/cose.xhtml#algorithms) maintained by IANA.
79    #[inline]
80    #[allow(
81        unused_variables,
82        reason = "Argument names are part of the documentation"
83    )]
84    fn from_cose_number(number: impl Into<i128>) -> Option<Self> {
85        None
86    }
87}
88
89pub fn test_hmac_algorithm_hmacsha256<HA: HmacAlgorithm>() {
90    let cose_5 = HA::from_cose_number(5i8);
91    assert!(
92        cose_5.is_some(),
93        "HMAC 256/256 must be recognised by COSE number 5"
94    );
95    assert_eq!(cose_5.as_ref().map(|a| a.len()), Some(32));
96}
embedded_cal/hmac.rs

embedded_cal/
hmac.rs
