esp_hal/
hmac.rs

1//! # Hash-based Message Authentication Code (HMAC) Accelerator
2//!
3//! ## Overview
4//! HMAC is a secure authentication technique that verifies the authenticity and
5//! integrity of a message with a pre-shared key. This module provides hardware
6//! acceleration for SHA256-HMAC generation using a key burned into an eFuse
7//! block.
8//!
9//! Main features:
10//!
11//! - Standard HMAC-SHA-256 algorithm.
12//! - Hash result only accessible by configurable hardware peripheral (in downstream mode).
13//! - Compatible to challenge-response authentication algorithm.
14//! - Generates required keys for the Digital Signature (DS) peripheral (in downstream mode).
15//! - Re-enables soft-disabled JTAG (in downstream mode).
16//!
17//! ## Configuration
18//! The HMAC module can be used in two modes - in ”upstream” mode the HMAC
19//! message is supplied by the user and the calculation result is read back by
20//! the user. In ”downstream” mode the HMAC module is used as a Key Derivation
21//! Function (KDF) for other internal hardwares.
22//!
23//! ### HMAC padding
24//!
25//! The HMAC padding is handled by the driver. In downstream mode, users do not
26//! need to input any message or apply padding. The HMAC module uses a default
27//! 32-byte pattern of 0x00 for re-enabling JTAG and a 32-byte pattern of 0xff
28//! for deriving the AES key for the DS module.
29//!
30//! ## Examples
31//! Visit the [HMAC] example to learn how to use the HMAC accelerator
32//!
33//! [HMAC]: https://github.com/esp-rs/esp-hal/blob/main/examples/peripheral/hmac/src/main.rs
34
35use core::convert::Infallible;
36
37use crate::{
38    pac,
39    peripherals::HMAC,
40    reg_access::{AlignmentHelper, SocDependentEndianess},
41    system::{GenericPeripheralGuard, Peripheral as PeripheralEnable},
42};
43
44/// Provides an interface for interacting with the HMAC hardware peripheral.
45/// It allows users to compute HMACs for cryptographic purposes, ensuring data
46/// integrity and authenticity.
47pub struct Hmac<'d> {
48    hmac: HMAC<'d>,
49    alignment_helper: AlignmentHelper<SocDependentEndianess>,
50    byte_written: usize,
51    next_command: NextCommand,
52    _guard: GenericPeripheralGuard<{ PeripheralEnable::Hmac as u8 }>,
53}
54
55/// HMAC interface error
56#[derive(Debug, Clone, Copy, PartialEq)]
57#[cfg_attr(feature = "defmt", derive(defmt::Format))]
58pub enum Error {
59    /// It means the purpose of the selected block does not match the
60    /// configured key purpose and the calculation will not proceed.
61    KeyPurposeMismatch,
62}
63
64/// The peripheral can be configured to deliver its output directly to the
65/// user. It can also deliver to other peripherals.
66#[derive(Debug, Clone, Copy, PartialEq)]
67#[cfg_attr(feature = "defmt", derive(defmt::Format))]
68#[allow(clippy::enum_variant_names, reason = "peripheral is unstable")]
69pub enum HmacPurpose {
70    /// HMAC is used to re-enable JTAG after soft-disabling it.
71    ToJtag     = 6,
72    /// HMAC is provided to the digital signature peripheral to decrypt the
73    /// private key.
74    ToDs       = 7,
75    /// Let the user provide a message and read the result.
76    ToUser     = 8,
77    /// HMAC is used for both the digital signature or JTAG.
78    ToDsOrJtag = 5,
79}
80
81#[derive(Debug, Clone, Copy, PartialEq)]
82#[cfg_attr(feature = "defmt", derive(defmt::Format))]
83/// Represents the key identifiers for the HMAC peripheral.
84pub enum KeyId {
85    /// Key 0.
86    Key0 = 0,
87    /// Key 1.
88    Key1 = 1,
89    /// Key 2.
90    Key2 = 2,
91    /// Key 3.
92    Key3 = 3,
93    /// Key 4.
94    Key4 = 4,
95    /// Key 5.
96    Key5 = 5,
97}
98
99enum NextCommand {
100    None,
101    MessageIng,
102    MessagePad,
103}
104
105impl<'d> Hmac<'d> {
106    /// Creates a new instance of the HMAC peripheral.
107    pub fn new(hmac: HMAC<'d>) -> Self {
108        let guard = GenericPeripheralGuard::new();
109
110        Self {
111            hmac,
112            alignment_helper: AlignmentHelper::default(),
113            byte_written: 64,
114            next_command: NextCommand::None,
115            _guard: guard,
116        }
117    }
118
119    fn regs(&self) -> &pac::hmac::RegisterBlock {
120        self.hmac.register_block()
121    }
122
123    /// Step 1. Enable HMAC module.
124    ///
125    /// Before these steps, the user shall set the peripheral clocks bits for
126    /// HMAC and SHA peripherals and clear the corresponding peripheral
127    /// reset bits.
128    pub fn init(&mut self) {
129        self.regs().set_start().write(|w| w.set_start().set_bit());
130        self.alignment_helper.reset();
131        self.byte_written = 64;
132        self.next_command = NextCommand::None;
133    }
134
135    /// Step 2. Configure HMAC keys and key purposes.
136    pub fn configure(&mut self, m: HmacPurpose, key_id: KeyId) -> nb::Result<(), Error> {
137        self.regs()
138            .set_para_purpose()
139            .write(|w| unsafe { w.purpose_set().bits(m as u8) });
140        self.regs()
141            .set_para_key()
142            .write(|w| unsafe { w.key_set().bits(key_id as u8) });
143        self.regs()
144            .set_para_finish()
145            .write(|w| w.set_para_end().set_bit());
146
147        if self.regs().query_error().read().query_check().bit_is_set() {
148            return Err(nb::Error::Other(Error::KeyPurposeMismatch));
149        }
150
151        Ok(())
152    }
153
154    /// Process the msg block after block
155    ///
156    /// Call this function as many times as necessary (msg.len() > 0)
157    pub fn update<'a>(&mut self, msg: &'a [u8]) -> nb::Result<&'a [u8], Infallible> {
158        if self.is_busy() {
159            return Err(nb::Error::WouldBlock);
160        }
161
162        self.next_command();
163
164        let remaining = self.write_data(msg).unwrap();
165
166        Ok(remaining)
167    }
168
169    /// Finalizes the HMAC computation and retrieves the resulting hash output.
170    pub fn finalize(&mut self, output: &mut [u8]) -> nb::Result<(), Infallible> {
171        if self.is_busy() {
172            return Err(nb::Error::WouldBlock);
173        }
174
175        self.next_command();
176
177        let msg_len = self.byte_written as u64;
178
179        nb::block!(self.write_data(&[0x80])).unwrap();
180        nb::block!(self.flush_data()).unwrap();
181        self.next_command();
182        debug_assert!(self.byte_written.is_multiple_of(4));
183
184        self.padding(msg_len);
185
186        // Checking if the message is one block including padding
187        if msg_len < 64 + 56 {
188            self.regs()
189                .one_block()
190                .write(|w| w.set_one_block().set_bit());
191
192            while self.is_busy() {}
193        }
194
195        self.alignment_helper.volatile_read_regset(
196            #[cfg(esp32s2)]
197            self.regs().rd_result_(0).as_ptr(),
198            #[cfg(not(esp32s2))]
199            self.regs().rd_result_mem(0).as_ptr(),
200            output,
201            core::cmp::min(output.len(), 32),
202        );
203
204        self.regs()
205            .set_result_finish()
206            .write(|w| w.set_result_end().set_bit());
207        self.byte_written = 64;
208        self.next_command = NextCommand::None;
209        Ok(())
210    }
211
212    fn is_busy(&mut self) -> bool {
213        self.regs().query_busy().read().busy_state().bit_is_set()
214    }
215
216    fn next_command(&mut self) {
217        match self.next_command {
218            NextCommand::MessageIng => {
219                self.regs()
220                    .set_message_ing()
221                    .write(|w| w.set_text_ing().set_bit());
222            }
223            NextCommand::MessagePad => {
224                self.regs()
225                    .set_message_pad()
226                    .write(|w| w.set_text_pad().set_bit());
227            }
228            NextCommand::None => {}
229        }
230        self.next_command = NextCommand::None;
231    }
232
233    fn write_data<'a>(&mut self, incoming: &'a [u8]) -> nb::Result<&'a [u8], Infallible> {
234        let (remaining, bound_reached) = self.alignment_helper.aligned_volatile_copy(
235            #[cfg(esp32s2)]
236            self.regs().wr_message_(0).as_ptr(),
237            #[cfg(not(esp32s2))]
238            self.regs().wr_message_mem(0).as_ptr(),
239            incoming,
240            64,
241            self.byte_written % 64,
242        );
243
244        self.byte_written = self
245            .byte_written
246            .wrapping_add(incoming.len() - remaining.len());
247
248        if bound_reached {
249            self.regs()
250                .set_message_one()
251                .write(|w| w.set_text_one().set_bit());
252
253            if remaining.len() >= 56 {
254                self.next_command = NextCommand::MessageIng;
255            } else {
256                self.next_command = NextCommand::MessagePad;
257            }
258        }
259
260        Ok(remaining)
261    }
262
263    fn flush_data(&mut self) -> nb::Result<(), Infallible> {
264        if self.is_busy() {
265            return Err(nb::Error::WouldBlock);
266        }
267
268        let flushed = self.alignment_helper.flush_to(
269            #[cfg(esp32s2)]
270            self.regs().wr_message_(0).as_ptr(),
271            #[cfg(not(esp32s2))]
272            self.regs().wr_message_mem(0).as_ptr(),
273            self.byte_written % 64,
274        );
275
276        self.byte_written = self.byte_written.wrapping_add(flushed);
277        if flushed > 0 && self.byte_written.is_multiple_of(64) {
278            self.regs()
279                .set_message_one()
280                .write(|w| w.set_text_one().set_bit());
281            while self.is_busy() {}
282            self.next_command = NextCommand::MessagePad;
283        }
284
285        Ok(())
286    }
287
288    fn padding(&mut self, msg_len: u64) {
289        let mod_cursor = self.byte_written % 64;
290
291        // The padding will be spanned over 2 blocks
292        if mod_cursor > 56 {
293            let pad_len = 64 - mod_cursor;
294            self.alignment_helper.volatile_write(
295                #[cfg(esp32s2)]
296                self.regs().wr_message_(0).as_ptr(),
297                #[cfg(not(esp32s2))]
298                self.regs().wr_message_mem(0).as_ptr(),
299                0_u8,
300                pad_len,
301                mod_cursor,
302            );
303            self.regs()
304                .set_message_one()
305                .write(|w| w.set_text_one().set_bit());
306            self.byte_written = self.byte_written.wrapping_add(pad_len);
307            debug_assert!(self.byte_written.is_multiple_of(64));
308            while self.is_busy() {}
309            self.next_command = NextCommand::MessagePad;
310            self.next_command();
311        }
312
313        let mod_cursor = self.byte_written % 64;
314        let pad_len = 64 - mod_cursor - core::mem::size_of::<u64>();
315
316        self.alignment_helper.volatile_write(
317            #[cfg(esp32s2)]
318            self.regs().wr_message_(0).as_ptr(),
319            #[cfg(not(esp32s2))]
320            self.regs().wr_message_mem(0).as_ptr(),
321            0_u8,
322            pad_len,
323            mod_cursor,
324        );
325
326        self.byte_written = self.byte_written.wrapping_add(pad_len);
327
328        assert_eq!(self.byte_written % 64, 64 - core::mem::size_of::<u64>());
329
330        // Add padded key
331        let len_mem = (msg_len * 8).to_be_bytes();
332
333        self.alignment_helper.aligned_volatile_copy(
334            #[cfg(esp32s2)]
335            self.regs().wr_message_(0).as_ptr(),
336            #[cfg(not(esp32s2))]
337            self.regs().wr_message_mem(0).as_ptr(),
338            &len_mem,
339            64,
340            64 - core::mem::size_of::<u64>(),
341        );
342        self.regs()
343            .set_message_one()
344            .write(|w| w.set_text_one().set_bit());
345
346        while self.is_busy() {}
347    }
348}
esp_hal/hmac.rs

esp_hal/
hmac.rs
