Skip to main content

esp_hal/
ecc.rs

1//! # Elliptic Curve Cryptography (ECC) Accelerator
2//!
3//! ## Overview
4//!
5//! Elliptic Curve Cryptography (ECC) is an approach to public-key cryptography
6//! based on the algebraic structure of elliptic curves. ECC allows smaller
7//! keys compared to RSA cryptography while providing equivalent security.
8//!
9//! ECC Accelerator can complete various calculation based on different
10//! elliptic curves, thus accelerating ECC algorithm and ECC-derived
11//! algorithms (such as ECDSA).
12
13use core::{marker::PhantomData, ptr::NonNull};
14
15use procmacros::BuilderLite;
16
17#[cfg(ecc_supports_enhanced_security)]
18use crate::efuse::ChipRevision;
19use crate::{
20    Blocking,
21    DriverMode,
22    interrupt::InterruptHandler,
23    pac::{self, ecc::mult_conf::KEY_LENGTH},
24    peripherals::{ECC, Interrupt},
25    private::Sealed,
26    system::{self, CryptoClockGuard, GenericPeripheralGuard},
27    work_queue::{Handle, Poll, Status, VTable, WorkQueue, WorkQueueDriver, WorkQueueFrontend},
28};
29
30/// This macro defines 4 other macros:
31/// - `doc_summary` that takes the first line of the documentation and returns it as a string
32/// - `result_type` that generates the return types for each operation
33/// - `operation` that generates the operation function
34/// - `backend_operation` that generates the backend operation function
35///
36/// These generated macros can then be fed to `for_each_ecc_working_mode!` to generate operations
37/// the device supports.
38macro_rules! define_operations {
39    ($($op:tt {
40        // The first line is used for summary, and it is prepended with `# ` on the driver method.
41        docs: [$first_line:literal $(, $lines:literal)*],
42        // The driver method name
43        function: $function:ident,
44        // Whether the operation is modular, i.e. whether it needs a modulus argument.
45        $(modular_arithmetic_method: $is_modular:literal,)?
46        // Whether the operation does point verification first.
47        $(verifies_point: $verifies_point:literal,)?
48        // Input parameters. This determines the name and order of the function arguments,
49        // as well as which memory block they will be written to. Depending on the value of
50        // cfg(ecc_separate_jacobian_point_memory), qx, qy and qz may be mapped to px, py and k.
51        inputs: [$($input:ident),*],
52        // What data does the output contain?
53        // - Scalar (and which memory block contains the scalar)
54        // - AffinePoint
55        // - JacobianPoint
56        returns: [
57            $(
58                // What data is computed may be device specific.
59                $(#[$returns_meta:meta])*
60                $returns:ident $({ const $c:ident: $t:tt = $v:expr })?
61            ),*
62        ]
63    }),*) => {
64        macro_rules! doc_summary {
65            $(
66                ($op) => { $first_line };
67            )*
68        }
69        macro_rules! result_type {
70            $(
71                ($op) => {
72                    #[doc = concat!("A marker type representing ", doc_summary!($op))]
73                    #[non_exhaustive]
74                    pub struct $op;
75
76                    impl crate::private::Sealed for $op {}
77
78                    impl EccOperation for $op {
79                        const WORK_MODE: WorkMode = WorkMode::$op;
80                        const VERIFIES_POINT: bool = $crate::if_set!($($verifies_point)?, false);
81                    }
82
83                    paste::paste! {
84                        $(
85                            $(#[$returns_meta])*
86                            impl [<OperationReturns $returns>] for $op {
87                                $(
88                                    const $c: $t = $v;
89                                )?
90                            }
91                        )*
92
93                        $(
94                            const _: bool = $verifies_point; // I just need this ignored.
95                            impl OperationVerifiesPoint for $op {}
96                        )?
97                    }
98                };
99            )*
100        }
101        macro_rules! driver_method {
102            $(
103                ($op) => {
104                    #[doc = concat!("# ", $first_line)]
105                    $(#[doc = $lines])*
106                    #[doc = r"
107
108# Errors
109
110[`OperationError::ParameterLengthMismatch`] if an input does not match the curve's size."]
111                    #[cfg_attr(ecc_has_curve_sm2, doc = "\n[`OperationError::UnsupportedCurve`] if SM2 is disabled by eFuse.")]
112                    #[inline]
113                    pub fn $function<'op>(
114                        &'op mut self,
115                        curve: EllipticCurve,
116                        $(#[cfg($is_modular)] modulus: EccModBase,)?
117                        $($input: &[u8],)*
118                    ) -> Result<EccResultHandle<'op, $op>, OperationError> {
119                        curve.check_parameters([$($input),*])?;
120
121                        paste::paste! {
122                            $(
123                                self.info().write_mem(self.info().[<$input _mem>](), $input);
124                            )*
125                        };
126
127                        #[cfg(ecc_has_modular_arithmetic)]
128                        let mod_base = $crate::if_set! {
129                            $(
130                                {
131                                    $crate::ignore!($is_modular);
132                                    modulus
133                                }
134                            )?,
135                            // else
136                            EccModBase::OrderOfCurve
137                        };
138
139                        Ok(self.run_operation::<$op>(
140                            curve,
141                            #[cfg(ecc_has_modular_arithmetic)] mod_base,
142                        ))
143                    }
144                };
145            )*
146        }
147
148        macro_rules! backend_operation {
149            $(
150                ($op) => {
151                    #[doc = concat!("Configures a new ", $first_line, " operation with the given inputs, to be executed on [`EccBackend`].")]
152                    ///
153                    /// Outputs need to be assigned separately before executing the operation.
154                    ///
155                    /// # Errors
156                    ///
157                    /// [`OperationError::ParameterLengthMismatch`] if an input does not match the curve's size.
158                    #[cfg_attr(ecc_has_curve_sm2, doc = "\n[`OperationError::UnsupportedCurve`] if SM2 is disabled by eFuse.")]
159                    pub fn $function<'op>(
160                        self,
161                        $(#[cfg($is_modular)] modulus: EccModBase,)?
162                        $($input: &'op [u8],)*
163                    ) -> Result<EccBackendOperation<'op, $op>, OperationError> {
164                        self.check_parameters([&$($input,)*])?;
165
166                        #[cfg(ecc_has_modular_arithmetic)]
167                        let mod_base = $crate::if_set! {
168                            $(
169                                {
170                                    $crate::ignore!($is_modular);
171                                    modulus
172                                }
173                            )?,
174                            // else
175                            EccModBase::OrderOfCurve
176                        };
177
178                        let work_item = EccWorkItem {
179                            curve: self,
180                            operation: WorkMode::$op,
181                            cancelled: false,
182                            #[cfg(ecc_has_modular_arithmetic)]
183                            mod_base,
184                            inputs: {
185                                let mut inputs = MemoryPointers::default();
186                                $(
187                                    paste::paste! {
188                                        inputs.[<set_ $input>](NonNull::from($input));
189                                    };
190                                )*
191                                inputs
192                            },
193                            point_verification_result: false,
194                            outputs: MemoryPointers::default(),
195                        };
196
197                        Ok(EccBackendOperation::new(work_item))
198                    }
199                };
200            )*
201        }
202    }
203}
204
205define_operations! {
206    AffinePointMultiplication {
207        docs: [
208            "Base Point Multiplication",
209            "",
210            "This operation performs `(Qx, Qy) = k * (Px, Py)`."
211        ],
212        function: affine_point_multiplication,
213        inputs: [k, px, py],
214        returns: [AffinePoint]
215    },
216
217    AffinePointVerification {
218        docs: [
219            "Base Point Verification",
220            "",
221            "This operation verifies whether Point (Px, Py) is on the selected elliptic curve."
222        ],
223        function: affine_point_verification,
224        verifies_point: true,
225        inputs: [px, py],
226        returns: []
227    },
228
229    AffinePointVerificationAndMultiplication {
230        docs: [
231            "Base Point Verification and Multiplication",
232            "",
233            "This operation verifies whether Point (Px, Py) is on the selected elliptic curve and performs `(Qx, Qy) = k * (Px, Py)`."
234        ],
235        function: affine_point_verification_multiplication,
236        verifies_point: true,
237        inputs: [k, px, py],
238        returns: [
239            AffinePoint,
240            #[cfg(ecc_separate_jacobian_point_memory)]
241            JacobianPoint
242        ]
243    },
244
245    AffinePointAddition {
246        docs: [
247            "Point Addition",
248            "",
249            "This operation performs `(Rx, Ry) = (Jx, Jy, Jz) = (Px, Py, 1) + (Qx, Qy, Qz)`."
250        ],
251        function: affine_point_addition,
252        inputs: [px, py, qx, qy, qz],
253        returns: [
254            AffinePoint,
255            #[cfg(ecc_separate_jacobian_point_memory)]
256            JacobianPoint
257        ]
258    },
259
260    JacobianPointMultiplication {
261        docs: [
262            "Jacobian Point Multiplication",
263            "",
264            "This operation performs `(Qx, Qy, Qz) = k * (Px, Py, 1)`."
265        ],
266        function: jacobian_point_multiplication,
267        inputs: [k, px, py],
268        returns: [
269            JacobianPoint
270        ]
271    },
272
273    JacobianPointVerification {
274        docs: [
275            "Jacobian Point Verification",
276            "",
277            "This operation verifies whether Point (Qx, Qy, Qz) is on the selected elliptic curve."
278        ],
279        function: jacobian_point_verification,
280        verifies_point: true,
281        inputs: [qx, qy, qz],
282        returns: [
283            JacobianPoint
284        ]
285    },
286
287    AffinePointVerificationAndJacobianPointMultiplication {
288        docs: [
289            "Base Point Verification + Jacobian Point Multiplication",
290            "",
291            "This operation first verifies whether Point (Px, Py) is on the selected elliptic curve. If yes, it performs `(Qx, Qy, Qz) = k * (Px, Py, 1)`."
292        ],
293        function: affine_point_verification_jacobian_multiplication,
294        verifies_point: true,
295        inputs: [k, px, py],
296        returns: [
297            JacobianPoint
298        ]
299    },
300
301    FiniteFieldDivision {
302        docs: [
303            "Finite Field Division",
304            "",
305            "This operation performs `R = Py * k^{−1} mod p`."
306        ],
307        function: finite_field_division,
308        inputs: [k, py],
309        returns: [
310            Scalar { const LOCATION: ScalarResultLocation = ScalarResultLocation::Py }
311        ]
312    },
313
314    ModularAddition {
315        docs: [
316            "Modular Addition",
317            "",
318            "This operation performs `R = Px + Py mod p`."
319        ],
320        function: modular_addition,
321        modular_arithmetic_method: true,
322        inputs: [px, py],
323        returns: [
324            Scalar { const LOCATION: ScalarResultLocation = ScalarResultLocation::Px }
325        ]
326    },
327
328    ModularSubtraction {
329        docs: [
330            "Modular Subtraction",
331            "",
332            "This operation performs `R = Px - Py mod p`."
333        ],
334        function: modular_subtraction,
335        modular_arithmetic_method: true,
336        inputs: [px, py],
337        returns: [
338            Scalar { const LOCATION: ScalarResultLocation = ScalarResultLocation::Px }
339        ]
340    },
341
342    ModularMultiplication {
343        docs: [
344            "Modular Multiplication",
345            "",
346            "This operation performs `R = Px * Py mod p`."
347        ],
348        function: modular_multiplication,
349        modular_arithmetic_method: true,
350        inputs: [px, py],
351        returns: [
352            Scalar { const LOCATION: ScalarResultLocation = ScalarResultLocation::Py }
353        ]
354    },
355
356    ModularDivision {
357        docs: [
358            "Modular Division",
359            "",
360            "This operation performs `R = Px * Py^{−1} mod p`."
361        ],
362        function: modular_division,
363        modular_arithmetic_method: true,
364        inputs: [px, py],
365        returns: [
366            Scalar { const LOCATION: ScalarResultLocation = ScalarResultLocation::Py }
367        ]
368    }
369}
370
371const MEM_BLOCK_SIZE: usize = property!("ecc.mem_block_size");
372
373/// The ECC Accelerator driver.
374///
375/// Unlike commonly used standards, this driver operates on **little-endian** data.
376pub struct Ecc<'d, Dm: DriverMode> {
377    _ecc: ECC<'d>,
378    phantom: PhantomData<Dm>,
379    _memory_guard: EccMemoryPowerGuard,
380    _guard: GenericPeripheralGuard<{ system::Peripheral::Ecc as u8 }>,
381    _clock_guard: CryptoClockGuard,
382}
383
384struct EccMemoryPowerGuard;
385
386impl EccMemoryPowerGuard {
387    fn new() -> Self {
388        #[cfg(soc_has_pcr)]
389        crate::peripherals::PCR::regs()
390            .ecc_pd_ctrl()
391            .modify(|_, w| {
392                w.ecc_mem_force_pd().clear_bit();
393                w.ecc_mem_force_pu().set_bit();
394                w.ecc_mem_pd().clear_bit()
395            });
396        Self
397    }
398}
399
400impl Drop for EccMemoryPowerGuard {
401    fn drop(&mut self) {
402        #[cfg(soc_has_pcr)]
403        crate::peripherals::PCR::regs()
404            .ecc_pd_ctrl()
405            .modify(|_, w| {
406                w.ecc_mem_force_pd().clear_bit();
407                w.ecc_mem_force_pu().clear_bit();
408                w.ecc_mem_pd().set_bit()
409            });
410    }
411}
412
413/// ECC peripheral configuration.
414///
415/// The default turns enhanced security on, where the chip supports it.
416#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Hash, BuilderLite)]
417#[cfg_attr(feature = "defmt", derive(defmt::Format))]
418pub struct Config {
419    /// Force-enables the register clock.
420    force_enable_reg_clock: bool,
421
422    /// Force-enables the memory clock.
423    #[cfg(ecc_has_memory_clock_gate)]
424    force_enable_mem_clock: bool,
425
426    /// Enables constant time operation and minimized power consumption variation for
427    /// point-multiplication operations.
428    ///
429    /// Turning it off makes a point multiplication faster by an amount that depends on the
430    /// scalar's bit pattern. The time then exposes the scalar to timing-based side-channel
431    /// attacks. Turn it off only for a public scalar.
432    ///
433    /// `None` enables the mode where the chip revision supports it. Where it does not, `None`
434    /// logs a warning and `Some(true)` is refused with
435    /// [`ConfigError::EnhancedSecurityUnsupported`]. A caller that needs constant time passes
436    /// `true`.
437    ///
438    /// Default value: `None`.
439    #[cfg_attr(
440        esp32h2,
441        doc = r"
442
443Only available on chip revision 1.2 and above."
444    )]
445    #[cfg(ecc_supports_enhanced_security)]
446    enhanced_security: Option<bool>,
447}
448
449/// ECC configuration error.
450#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
451#[cfg_attr(feature = "defmt", derive(defmt::Format))]
452#[non_exhaustive]
453pub enum ConfigError {
454    /// The configuration asks for enhanced security, and this chip revision does not support it.
455    ///
456    /// Only the ESP32-H2 below revision 1.2 lacks it. The default configuration is accepted there,
457    /// turns the mode off and logs a warning.
458    #[cfg(ecc_supports_enhanced_security)]
459    EnhancedSecurityUnsupported,
460}
461
462/// Returns whether this chip revision has the enhanced security mode.
463#[cfg(ecc_supports_enhanced_security)]
464fn enhanced_security_supported() -> bool {
465    !cfg!(esp32h2) || crate::soc::chip_revision_above(ChipRevision::from_combined(102))
466}
467
468/// Returns whether `config` turns enhanced security on, with `None` resolved for this chip
469/// revision.
470#[cfg(ecc_supports_enhanced_security)]
471fn enhanced_security(config: &Config) -> Result<bool, ConfigError> {
472    match config.enhanced_security {
473        None if !enhanced_security_supported() => {
474            warn!(
475                "No ECC enhanced security on this chip revision: point multiplication exposes a private scalar to a timing side channel"
476            );
477            Ok(false)
478        }
479        None => Ok(true),
480        Some(true) if !enhanced_security_supported() => {
481            Err(ConfigError::EnhancedSecurityUnsupported)
482        }
483        Some(on) => Ok(on),
484    }
485}
486
487fn check_config(_config: &Config) -> Result<(), ConfigError> {
488    #[cfg(ecc_supports_enhanced_security)]
489    enhanced_security(_config)?;
490
491    Ok(())
492}
493
494/// ECC operation error.
495#[derive(Debug, Clone, Copy, PartialEq, Eq)]
496pub enum OperationError {
497    /// The length of the arguments do not match the length required by the curve.
498    ParameterLengthMismatch,
499
500    /// Point verification failed.
501    PointNotOnCurve,
502
503    /// The selected curve is not supported.
504    UnsupportedCurve,
505}
506
507/// Modulus base.
508#[cfg(ecc_has_modular_arithmetic)]
509#[derive(Debug, Clone, Copy, PartialEq, Eq)]
510pub enum EccModBase {
511    /// The order of the curve.
512    OrderOfCurve = 0,
513
514    /// Prime modulus.
515    PrimeModulus = 1,
516}
517
518for_each_ecc_curve! {
519    (all $(( $id:literal, $name:ident, $bits:literal )),*) => {
520        /// Represents supported elliptic curves for cryptographic operations.
521        ///
522        /// The methods that represent operations require the `EccBackend` to be started before use.
523        #[derive(Clone, Copy, PartialEq, Eq, Debug)]
524        #[cfg_attr(feature = "defmt", derive(defmt::Format))]
525        pub enum EllipticCurve {
526            $(
527                #[doc = concat!("The ", stringify!($name), " elliptic curve, a ", $bits, "-bit curve.")]
528                $name,
529            )*
530        }
531        impl EllipticCurve {
532            /// Returns whether the curve is available for hardware operations.
533            #[cfg_attr(ecc_has_curve_sm2, doc = "\nSM2 is disabled when the `DIS_SM_CRYPT` eFuse is set.")]
534            #[instability::unstable]
535            pub fn is_supported(self) -> bool {
536                match self {
537                    #[cfg(ecc_has_curve_sm2)]
538                    Self::Sm2 => !crate::efuse::read_bit(crate::efuse::DIS_SM_CRYPT),
539                    _ => true,
540                }
541            }
542
543            /// Returns the size of the elliptic curve in bytes.
544            pub const fn size(self) -> usize {
545                match self {
546                    $(
547                        EllipticCurve::$name => $bits / 8,
548                    )*
549                }
550            }
551        }
552    };
553}
554
555for_each_ecc_working_mode! {
556    (all $(($wm_id:literal, $op:tt)),*) => {
557        impl EllipticCurve {
558            fn check_parameters<const N: usize>(&self, params: [&[u8]; N]) -> Result<(), OperationError> {
559                if !self.is_supported() {
560                    return Err(OperationError::UnsupportedCurve);
561                }
562
563                self.size_check(params)
564            }
565
566            fn size_check<const N: usize>(&self, params: [&[u8]; N]) -> Result<(), OperationError> {
567                let bytes = self.size();
568
569                if params.iter().any(|p| p.len() != bytes) {
570                    return Err(OperationError::ParameterLengthMismatch);
571                }
572
573                Ok(())
574            }
575
576            $(
577                // Macro defined by `define_operations`
578                backend_operation!($op);
579            )*
580        }
581    };
582}
583
584impl<'d> Ecc<'d, Blocking> {
585    /// Creates a new instance in [Blocking] mode, with the given configuration.
586    pub fn new(ecc: ECC<'d>, config: Config) -> Result<Self, ConfigError> {
587        let clock_guard = CryptoClockGuard::new();
588        let this = Self {
589            _ecc: ecc,
590            phantom: PhantomData,
591            _memory_guard: EccMemoryPowerGuard::new(),
592            _guard: GenericPeripheralGuard::new(),
593            _clock_guard: clock_guard,
594        };
595
596        this.info().apply_config(&config)?;
597
598        Ok(this)
599    }
600}
601
602impl crate::private::Sealed for Ecc<'_, Blocking> {}
603
604#[instability::unstable]
605impl crate::interrupt::InterruptConfigurable for Ecc<'_, Blocking> {
606    fn set_interrupt_handler(&mut self, handler: InterruptHandler) {
607        self.set_interrupt_handler(handler);
608    }
609}
610
611struct Info {
612    regs: &'static pac::ecc::RegisterBlock,
613}
614
615impl Info {
616    fn reset(&self) {
617        self.regs.mult_conf().reset()
618    }
619
620    fn apply_config(&self, config: &Config) -> Result<(), ConfigError> {
621        #[cfg(ecc_supports_enhanced_security)]
622        let enhanced_security = enhanced_security(config)?;
623
624        self.regs.mult_conf().modify(|_, w| {
625            w.clk_en().bit(config.force_enable_reg_clock);
626
627            #[cfg(ecc_has_memory_clock_gate)]
628            w.mem_clock_gate_force_on()
629                .bit(config.force_enable_mem_clock);
630
631            #[cfg(ecc_supports_enhanced_security)]
632            if enhanced_security_supported() {
633                w.security_mode().bit(enhanced_security);
634            }
635
636            w
637        });
638
639        Ok(())
640    }
641
642    fn check_point_verification_result(&self) -> Result<(), OperationError> {
643        if self
644            .regs
645            .mult_conf()
646            .read()
647            .verification_result()
648            .bit_is_set()
649        {
650            Ok(())
651        } else {
652            Err(OperationError::PointNotOnCurve)
653        }
654    }
655
656    #[inline]
657    fn write_mem(&self, mut word_ptr: *mut u32, data: &[u8]) {
658        // Note that at least the C2 requires writing this memory in words.
659
660        debug_assert!(data.len() <= MEM_BLOCK_SIZE);
661
662        #[cfg(ecc_zero_extend_writes)]
663        let end = word_ptr.wrapping_byte_add(MEM_BLOCK_SIZE);
664
665        let (chunks, remainder) = data.as_chunks::<4>();
666        debug_assert!(remainder.is_empty());
667
668        for word_bytes in chunks {
669            unsafe { word_ptr.write_volatile(u32::from_le_bytes(*word_bytes)) };
670            word_ptr = word_ptr.wrapping_add(1);
671        }
672
673        #[cfg(ecc_zero_extend_writes)]
674        while word_ptr < end {
675            unsafe { word_ptr.write_volatile(0) };
676            word_ptr = word_ptr.wrapping_add(1);
677        }
678    }
679
680    #[inline]
681    fn read_mem(&self, mut word_ptr: *const u32, out: &mut [u8]) {
682        let (chunks, _) = out.as_chunks_mut::<4>();
683        for word_bytes in chunks {
684            let word = unsafe { word_ptr.read_volatile() };
685            word_ptr = word_ptr.wrapping_add(1);
686            *word_bytes = word.to_le_bytes();
687        }
688    }
689
690    fn k_mem(&self) -> *mut u32 {
691        self.regs.k_mem(0).as_ptr()
692    }
693
694    fn px_mem(&self) -> *mut u32 {
695        self.regs.px_mem(0).as_ptr()
696    }
697
698    fn py_mem(&self) -> *mut u32 {
699        self.regs.py_mem(0).as_ptr()
700    }
701
702    fn qx_mem(&self) -> *mut u32 {
703        cfg_select! {
704            ecc_separate_jacobian_point_memory => self.regs.qx_mem(0).as_ptr(),
705            _ => self.regs.px_mem(0).as_ptr(),
706        }
707    }
708
709    fn qy_mem(&self) -> *mut u32 {
710        cfg_select! {
711            ecc_separate_jacobian_point_memory => self.regs.qy_mem(0).as_ptr(),
712            _ => self.regs.py_mem(0).as_ptr(),
713        }
714    }
715
716    fn qz_mem(&self) -> *mut u32 {
717        cfg_select! {
718            ecc_separate_jacobian_point_memory => self.regs.qz_mem(0).as_ptr(),
719            _ => self.regs.k_mem(0).as_ptr(),
720        }
721    }
722
723    fn read_point_result(&self, x: &mut [u8], y: &mut [u8]) {
724        self.read_mem(self.px_mem(), x);
725        self.read_mem(self.py_mem(), y);
726    }
727
728    fn read_jacobian_result(&self, qx: &mut [u8], qy: &mut [u8], qz: &mut [u8]) {
729        self.read_mem(self.qx_mem(), qx);
730        self.read_mem(self.qy_mem(), qy);
731        self.read_mem(self.qz_mem(), qz);
732    }
733
734    /// Clears all peripheral memory blocks.
735    #[cfg(clear_crypto_secrets)]
736    fn clear_secrets(&self) {
737        self.zero_mem(self.k_mem());
738        self.zero_mem(self.px_mem());
739        self.zero_mem(self.py_mem());
740
741        #[cfg(ecc_separate_jacobian_point_memory)]
742        {
743            self.zero_mem(self.qx_mem());
744            self.zero_mem(self.qy_mem());
745            self.zero_mem(self.qz_mem());
746        }
747    }
748
749    #[cfg(clear_crypto_secrets)]
750    fn zero_mem(&self, mut word_ptr: *mut u32) {
751        for _ in 0..(MEM_BLOCK_SIZE / 4) {
752            unsafe { word_ptr.write_volatile(0) };
753            word_ptr = word_ptr.wrapping_add(1);
754        }
755    }
756
757    fn is_busy(&self) -> bool {
758        self.regs.mult_conf().read().start().bit_is_set()
759    }
760
761    fn start_operation(
762        &self,
763        mode: WorkMode,
764        curve: EllipticCurve,
765        #[cfg(ecc_has_modular_arithmetic)] mod_base: EccModBase,
766    ) {
767        let curve_variant;
768        for_each_ecc_curve! {
769            (all $(($_id:tt, $name:ident, $_bits:tt)),*) => {
770                curve_variant = match curve {
771                    $(EllipticCurve::$name => KEY_LENGTH::$name,)*
772                }
773            };
774        };
775        self.regs.mult_conf().modify(|_, w| unsafe {
776            w.work_mode().bits(mode as u8);
777            w.key_length().variant(curve_variant);
778
779            #[cfg(ecc_has_modular_arithmetic)]
780            w.mod_base().bit(mod_base as u8 == 1);
781
782            w.start().set_bit()
783        });
784    }
785}
786
787// Broken into separate macro invocations per item, to make the "Expand macro" LSP output more
788// readable
789
790for_each_ecc_working_mode! {
791    (all $(( $id:literal, $mode:tt )),*) => {
792        #[derive(Clone, Copy)]
793        #[doc(hidden)]
794        /// Represents the operational modes for elliptic curve or modular arithmetic
795        /// computations.
796        pub enum WorkMode {
797            $(
798                $mode = $id,
799            )*
800        }
801    };
802}
803
804// Result type for each operation
805for_each_ecc_working_mode! {
806    (all $(( $id:literal, $mode:tt )),*) => {
807        $(
808            result_type!($mode);
809        )*
810    };
811}
812
813// The main driver implementation
814for_each_ecc_working_mode! {
815    (all $(( $id:literal, $mode:tt )),*) => {
816        impl<'d, Dm: DriverMode> Ecc<'d, Dm> {
817            fn info(&self) -> Info {
818                Info { regs: ECC::regs() }
819            }
820
821            fn run_operation<'op, O: EccOperation>(
822                &'op mut self,
823                curve: EllipticCurve,
824                #[cfg(ecc_has_modular_arithmetic)] mod_base: EccModBase,
825            ) -> EccResultHandle<'op, O> {
826                self.info().start_operation(
827                    O::WORK_MODE,
828                    curve,
829                    #[cfg(ecc_has_modular_arithmetic)] mod_base,
830                );
831
832                // wait for interrupt
833                while self.info().is_busy() {}
834
835                EccResultHandle::new(curve, self)
836            }
837
838            /// Applies the given configuration to the ECC peripheral.
839            pub fn apply_config(&mut self, config: &Config) -> Result<(), ConfigError> {
840                self.info().apply_config(config)
841            }
842
843            /// Resets the ECC peripheral.
844            pub fn reset(&mut self) {
845                self.info().reset()
846            }
847
848            /// Registers an interrupt handler for the ECC peripheral.
849            ///
850            /// Replaces any previously registered interrupt handlers.
851            #[instability::unstable]
852            pub fn set_interrupt_handler(&mut self, handler: InterruptHandler) {
853                for core in crate::system::Cpu::other() {
854                    crate::interrupt::disable(core, Interrupt::ECC);
855                }
856                crate::interrupt::bind_handler(Interrupt::ECC, handler);
857            }
858
859            $(
860                driver_method!($mode);
861            )*
862        }
863    };
864}
865
866/// Marks an ECC operation.
867pub trait EccOperation: Sealed {
868    /// Whether the operation verifies that the input point is on the curve.
869    const VERIFIES_POINT: bool;
870
871    /// Work mode
872    #[doc(hidden)]
873    const WORK_MODE: WorkMode;
874}
875
876/// Scalar result location.
877#[doc(hidden)]
878pub enum ScalarResultLocation {
879    /// The scalar value is stored in the `Px` memory location.
880    Px,
881    /// The scalar value is stored in the `Py` memory location.
882    Py,
883    /// The scalar value is stored in the `k` memory location.
884    K,
885}
886
887/// Marks operations that return a scalar value.
888pub trait OperationReturnsScalar: EccOperation {
889    /// Where the scalar value is stored.
890    #[doc(hidden)]
891    const LOCATION: ScalarResultLocation;
892}
893
894/// Marks operations that return a point in affine format.
895pub trait OperationReturnsAffinePoint: EccOperation {}
896
897/// Marks operations that return a point in Jacobian format.
898pub trait OperationReturnsJacobianPoint: EccOperation {}
899
900/// Marks operations that verify that the input point is on the curve.
901pub trait OperationVerifiesPoint: EccOperation {}
902
903/// The result of an ECC operation.
904///
905/// Used to read the result of an ECC operation. The available methods depend on
906/// the operation. An operation can compute multiple values, such as an affine point
907/// and a Jacobian point at the same time.
908#[must_use]
909pub struct EccResultHandle<'op, O>
910where
911    O: EccOperation,
912{
913    curve: EllipticCurve,
914    info: Info,
915    _marker: PhantomData<(&'op mut (), O)>,
916}
917
918impl<'op, O> EccResultHandle<'op, O>
919where
920    O: EccOperation,
921{
922    fn new<'d, Dm: DriverMode>(curve: EllipticCurve, driver: &'op mut Ecc<'d, Dm>) -> Self {
923        Self {
924            curve,
925            info: driver.info(),
926            _marker: PhantomData,
927        }
928    }
929
930    fn run_checks<const N: usize>(&self, params: [&[u8]; N]) -> Result<(), OperationError> {
931        self.curve.size_check(params)?;
932        if O::VERIFIES_POINT {
933            self.info.check_point_verification_result()?;
934        }
935        Ok(())
936    }
937
938    /// Returns whether the operation was successful.
939    ///
940    /// For operations that only perform point verification, this method returns whether the point
941    /// is on the curve. For operations that do not perform point verification, this method always
942    /// returns true.
943    pub fn success(&self) -> bool {
944        if O::VERIFIES_POINT {
945            self.info.check_point_verification_result().is_ok()
946        } else {
947            true
948        }
949    }
950
951    /// Retrieves the scalar result of the operation.
952    ///
953    /// # Errors
954    ///
955    /// [`OperationError`] when point verification failed, or when `out` is not the correct size.
956    pub fn read_scalar_result(&self, out: &mut [u8]) -> Result<(), OperationError>
957    where
958        O: OperationReturnsScalar,
959    {
960        self.run_checks([out])?;
961
962        match O::LOCATION {
963            ScalarResultLocation::Px => self.info.read_mem(self.info.px_mem(), out),
964            ScalarResultLocation::Py => self.info.read_mem(self.info.py_mem(), out),
965            ScalarResultLocation::K => self.info.read_mem(self.info.k_mem(), out),
966        }
967
968        Ok(())
969    }
970
971    /// Retrieves the affine point result of the operation.
972    ///
973    /// # Errors
974    ///
975    /// [`OperationError`] when point verification failed, or when `x` or `y` are not the correct
976    /// size.
977    pub fn read_affine_point_result(&self, x: &mut [u8], y: &mut [u8]) -> Result<(), OperationError>
978    where
979        O: OperationReturnsAffinePoint,
980    {
981        self.run_checks([x, y])?;
982        self.info.read_point_result(x, y);
983        Ok(())
984    }
985
986    /// Retrieves the Jacobian point result of the operation.
987    ///
988    /// # Errors
989    ///
990    /// [`OperationError`] when point verification failed, or when `x`, `y`, or `z` are not the
991    /// correct size.
992    pub fn read_jacobian_point_result(
993        &self,
994        x: &mut [u8],
995        y: &mut [u8],
996        z: &mut [u8],
997    ) -> Result<(), OperationError>
998    where
999        O: OperationReturnsJacobianPoint,
1000    {
1001        self.run_checks([x, y, z])?;
1002        self.info.read_jacobian_result(x, y, z);
1003        Ok(())
1004    }
1005}
1006
1007struct EccWorkItem {
1008    curve: EllipticCurve,
1009    operation: WorkMode,
1010    cancelled: bool,
1011    #[cfg(ecc_has_modular_arithmetic)]
1012    mod_base: EccModBase,
1013    inputs: MemoryPointers,
1014    point_verification_result: bool,
1015    outputs: MemoryPointers,
1016}
1017
1018#[derive(Default)]
1019struct MemoryPointers {
1020    // All of these pointers point to slices with curve-appropriate lengths.
1021    k: Option<NonNull<u8>>,
1022    px: Option<NonNull<u8>>,
1023    py: Option<NonNull<u8>>,
1024    #[cfg(ecc_separate_jacobian_point_memory)]
1025    qx: Option<NonNull<u8>>,
1026    #[cfg(ecc_separate_jacobian_point_memory)]
1027    qy: Option<NonNull<u8>>,
1028    #[cfg(ecc_separate_jacobian_point_memory)]
1029    qz: Option<NonNull<u8>>,
1030}
1031
1032impl MemoryPointers {
1033    fn set_scalar(&mut self, location: ScalarResultLocation, ptr: NonNull<[u8]>) {
1034        match location {
1035            ScalarResultLocation::Px => self.set_px(ptr),
1036            ScalarResultLocation::Py => self.set_py(ptr),
1037            ScalarResultLocation::K => self.set_k(ptr),
1038        }
1039    }
1040
1041    fn set_k(&mut self, ptr: NonNull<[u8]>) {
1042        self.k = Some(ptr.cast());
1043    }
1044
1045    fn set_px(&mut self, ptr: NonNull<[u8]>) {
1046        self.px = Some(ptr.cast());
1047    }
1048
1049    fn set_py(&mut self, ptr: NonNull<[u8]>) {
1050        self.py = Some(ptr.cast());
1051    }
1052
1053    fn set_qx(&mut self, ptr: NonNull<[u8]>) {
1054        cfg_select! {
1055            ecc_separate_jacobian_point_memory => {
1056                self.qx = Some(ptr.cast());
1057            }
1058            _ => {
1059                self.px = Some(ptr.cast());
1060            }
1061        }
1062    }
1063
1064    fn set_qy(&mut self, ptr: NonNull<[u8]>) {
1065        cfg_select! {
1066            ecc_separate_jacobian_point_memory => {
1067                self.qy = Some(ptr.cast());
1068            }
1069            _ => {
1070                self.py = Some(ptr.cast());
1071            }
1072        }
1073    }
1074
1075    fn set_qz(&mut self, ptr: NonNull<[u8]>) {
1076        cfg_select! {
1077            ecc_separate_jacobian_point_memory => {
1078                self.qz = Some(ptr.cast());
1079            }
1080            _ => {
1081                self.k = Some(ptr.cast());
1082            }
1083        }
1084    }
1085}
1086
1087// Safety: MemoryPointers is safe to share between threads, in the context of a WorkQueue. The
1088// WorkQueue ensures that only a single location can access the data. All the internals, except
1089// for the pointers, are Sync. The pointers are safe to share because they point at data that the
1090// ECC driver ensures can be accessed safely and soundly.
1091unsafe impl Sync for MemoryPointers {}
1092// Safety: we will not hold on to the pointers when the work item leaves the queue.
1093unsafe impl Send for MemoryPointers {}
1094
1095static ECC_WORK_QUEUE: WorkQueue<EccWorkItem> = WorkQueue::new();
1096
1097const ECC_VTABLE: VTable<EccWorkItem> = VTable {
1098    post: |driver, item| {
1099        let driver = unsafe { EccBackend::from_raw(driver) };
1100
1101        // Ensure driver is initialized
1102        if let DriverState::Uninitialized(ecc) = &driver.driver {
1103            // `EccBackend::new` checked the configuration.
1104            let mut ecc = unwrap!(Ecc::new(unsafe { ecc.clone_unchecked() }, driver.config));
1105            ecc.set_interrupt_handler(ecc_work_queue_handler);
1106            driver.driver = DriverState::Initialized(ecc);
1107        };
1108
1109        Some(driver.process(item))
1110    },
1111    poll: |driver, item| {
1112        let driver = unsafe { EccBackend::from_raw(driver) };
1113        driver.poll(item)
1114    },
1115    cancel: |driver, item| {
1116        let driver = unsafe { EccBackend::from_raw(driver) };
1117        driver.cancel(item);
1118    },
1119    stop: |driver| {
1120        let driver = unsafe { EccBackend::from_raw(driver) };
1121        driver.deinitialize()
1122    },
1123};
1124
1125enum DriverState<'d> {
1126    Uninitialized(ECC<'d>),
1127    Initialized(Ecc<'d, Blocking>),
1128}
1129
1130/// ECC processing backend.
1131///
1132/// Enables shared access to the device's ECC hardware using a work queue.
1133pub struct EccBackend<'d> {
1134    driver: DriverState<'d>,
1135    config: Config,
1136}
1137
1138impl<'d> EccBackend<'d> {
1139    /// Creates a new ECC backend, with the given configuration.
1140    ///
1141    /// The backend must be started with [`Self::start`] before it can execute ECC operations.
1142    pub fn new(ecc: ECC<'d>, config: Config) -> Result<Self, ConfigError> {
1143        check_config(&config)?;
1144
1145        Ok(Self {
1146            driver: DriverState::Uninitialized(ecc),
1147            config,
1148        })
1149    }
1150
1151    /// Registers the ECC driver to process ECC operations.
1152    ///
1153    /// The driver stops operating when the returned object is dropped.
1154    pub fn start(&mut self) -> EccWorkQueueDriver<'_, 'd> {
1155        EccWorkQueueDriver {
1156            inner: WorkQueueDriver::new(self, ECC_VTABLE, &ECC_WORK_QUEUE),
1157        }
1158    }
1159
1160    // WorkQueue callbacks. They may run in any context.
1161
1162    unsafe fn from_raw<'any>(ptr: NonNull<()>) -> &'any mut Self {
1163        unsafe { ptr.cast::<EccBackend<'_>>().as_mut() }
1164    }
1165
1166    fn process(&mut self, item: &mut EccWorkItem) -> Poll {
1167        let DriverState::Initialized(driver) = &mut self.driver else {
1168            unreachable!()
1169        };
1170
1171        let bytes = item.curve.size();
1172
1173        macro_rules! set_input {
1174            ($input:ident, $input_mem:ident) => {
1175                if let Some($input) = item.inputs.$input {
1176                    driver.info().write_mem(driver.info().$input_mem(), unsafe {
1177                        core::slice::from_raw_parts($input.as_ptr(), bytes)
1178                    });
1179                }
1180            };
1181        }
1182
1183        set_input!(k, k_mem);
1184        set_input!(px, px_mem);
1185        set_input!(py, py_mem);
1186
1187        #[cfg(ecc_separate_jacobian_point_memory)]
1188        {
1189            set_input!(qx, qx_mem);
1190            set_input!(qy, qy_mem);
1191            set_input!(qz, qz_mem);
1192        }
1193
1194        driver.info().start_operation(
1195            item.operation,
1196            item.curve,
1197            #[cfg(ecc_has_modular_arithmetic)]
1198            item.mod_base,
1199        );
1200        Poll::Pending(false)
1201    }
1202
1203    fn poll(&mut self, item: &mut EccWorkItem) -> Poll {
1204        let DriverState::Initialized(driver) = &mut self.driver else {
1205            unreachable!()
1206        };
1207
1208        if driver.info().is_busy() {
1209            return Poll::Pending(false);
1210        }
1211        if item.cancelled {
1212            return Poll::Ready(Status::Cancelled);
1213        }
1214
1215        let bytes = item.curve.size();
1216
1217        macro_rules! read_output {
1218            ($output:ident, $output_mem:ident) => {
1219                if let Some($output) = item.outputs.$output {
1220                    driver.info().read_mem(driver.info().$output_mem(), unsafe {
1221                        core::slice::from_raw_parts_mut($output.as_ptr(), bytes)
1222                    });
1223                }
1224            };
1225        }
1226
1227        read_output!(k, k_mem);
1228        read_output!(px, px_mem);
1229        read_output!(py, py_mem);
1230
1231        #[cfg(ecc_separate_jacobian_point_memory)]
1232        {
1233            read_output!(qx, qx_mem);
1234            read_output!(qy, qy_mem);
1235            read_output!(qz, qz_mem);
1236        }
1237
1238        item.point_verification_result = driver.info().check_point_verification_result().is_ok();
1239
1240        #[cfg(clear_crypto_secrets)]
1241        driver.info().clear_secrets();
1242
1243        Poll::Ready(Status::Completed)
1244    }
1245
1246    fn cancel(&mut self, item: &mut EccWorkItem) {
1247        let DriverState::Initialized(driver) = &mut self.driver else {
1248            unreachable!()
1249        };
1250        driver.reset();
1251
1252        // The operands may have already been written to the peripheral.
1253        #[cfg(clear_crypto_secrets)]
1254        driver.info().clear_secrets();
1255
1256        item.cancelled = true;
1257    }
1258
1259    fn deinitialize(&mut self) {
1260        if let DriverState::Initialized(ref ecc) = self.driver {
1261            self.driver = DriverState::Uninitialized(unsafe { ecc._ecc.clone_unchecked() });
1262        }
1263    }
1264}
1265
1266/// An active work queue driver.
1267///
1268/// This object must be kept around, otherwise ECC operations will never complete.
1269pub struct EccWorkQueueDriver<'t, 'd> {
1270    inner: WorkQueueDriver<'t, EccBackend<'d>, EccWorkItem>,
1271}
1272
1273impl<'t, 'd> EccWorkQueueDriver<'t, 'd> {
1274    /// Finishes processing the current work queue item, then stops the driver.
1275    pub fn stop(self) -> impl Future<Output = ()> {
1276        self.inner.stop()
1277    }
1278}
1279
1280#[crate::ram]
1281#[crate::handler]
1282fn ecc_work_queue_handler() {
1283    if !ECC_WORK_QUEUE.process() {
1284        // The queue may indicate that it needs to be polled again. In this case, we do not clear
1285        // the interrupt bit, which causes the interrupt to be re-handled.
1286        cfg_select! {
1287            any(esp32c5, esp32c61) => {
1288                let reg = ECC::regs().int_clr();
1289            }
1290            _ => {
1291                let reg = ECC::regs().mult_int_clr();
1292            }
1293        }
1294        reg.write(|w| w.calc_done().clear_bit_by_one());
1295    }
1296}
1297
1298/// An ECC operation that can be enqueued on the work queue.
1299pub struct EccBackendOperation<'op, O: EccOperation> {
1300    frontend: WorkQueueFrontend<EccWorkItem>,
1301    _marker: PhantomData<(&'op mut (), O)>,
1302}
1303
1304impl<'op, O: EccOperation> EccBackendOperation<'op, O> {
1305    fn new(work_item: EccWorkItem) -> Self {
1306        Self {
1307            frontend: WorkQueueFrontend::new(work_item),
1308            _marker: PhantomData,
1309        }
1310    }
1311
1312    /// Designate a buffer for the scalar result of the operation.
1313    ///
1314    /// Once the operation is processed, the result can be retrieved from the designated buffer.
1315    ///
1316    /// # Errors
1317    ///
1318    /// [`OperationError::ParameterLengthMismatch`] when `out` is not the correct size.
1319    pub fn with_scalar_result(mut self, out: &'op mut [u8]) -> Result<Self, OperationError>
1320    where
1321        O: OperationReturnsScalar,
1322    {
1323        self.frontend.data().curve.size_check([out])?;
1324
1325        self.frontend
1326            .data_mut()
1327            .outputs
1328            .set_scalar(O::LOCATION, NonNull::from(out));
1329
1330        Ok(self)
1331    }
1332
1333    /// Designate buffers for the affine point result of the operation.
1334    ///
1335    /// Once the operation is processed, the result can be retrieved from the designated buffers.
1336    ///
1337    /// # Errors
1338    ///
1339    /// [`OperationError::ParameterLengthMismatch`] when `x` or `y` are not the correct size.
1340    pub fn with_affine_point_result(
1341        mut self,
1342        px: &'op mut [u8],
1343        py: &'op mut [u8],
1344    ) -> Result<Self, OperationError>
1345    where
1346        O: OperationReturnsAffinePoint,
1347    {
1348        self.frontend.data().curve.size_check([px, py])?;
1349
1350        self.frontend.data_mut().outputs.set_px(NonNull::from(px));
1351        self.frontend.data_mut().outputs.set_py(NonNull::from(py));
1352
1353        Ok(self)
1354    }
1355
1356    /// Designate buffers for the Jacobian point result of the operation.
1357    ///
1358    /// Once the operation is processed, the result can be retrieved from the designated buffers.
1359    ///
1360    /// # Errors
1361    ///
1362    /// [`OperationError::ParameterLengthMismatch`] when `x`, `y`, or `z` are not the correct size.
1363    pub fn with_jacobian_point_result(
1364        mut self,
1365        qx: &'op mut [u8],
1366        qy: &'op mut [u8],
1367        qz: &'op mut [u8],
1368    ) -> Result<Self, OperationError>
1369    where
1370        O: OperationReturnsJacobianPoint,
1371    {
1372        self.frontend.data().curve.size_check([qx, qy, qz])?;
1373
1374        self.frontend.data_mut().outputs.set_qx(NonNull::from(qx));
1375        self.frontend.data_mut().outputs.set_qy(NonNull::from(qy));
1376        self.frontend.data_mut().outputs.set_qz(NonNull::from(qz));
1377
1378        Ok(self)
1379    }
1380
1381    /// Returns whether the input point is on the curve.
1382    ///
1383    /// The operation must be processed before this method returns a meaningful value.
1384    pub fn point_on_curve(&self) -> bool
1385    where
1386        O: OperationVerifiesPoint,
1387    {
1388        self.frontend.data().point_verification_result
1389    }
1390
1391    /// Starts processing the operation.
1392    ///
1393    /// The returned [`EccHandle`] must be polled to completion before the operation is considered
1394    /// complete.
1395    pub fn process(&mut self) -> EccHandle<'_> {
1396        EccHandle(self.frontend.post(&ECC_WORK_QUEUE))
1397    }
1398}
1399
1400/// A handle for an in-progress operation.
1401#[must_use]
1402pub struct EccHandle<'t>(Handle<'t, EccWorkItem>);
1403
1404impl EccHandle<'_> {
1405    /// Polls the status of the work item.
1406    ///
1407    /// Returns whether the item has been processed.
1408    #[inline]
1409    pub fn poll(&mut self) -> bool {
1410        self.0.poll()
1411    }
1412
1413    /// Polls the work item to completion, by busy-looping.
1414    ///
1415    /// Returns immediately if `poll` returns `true`.
1416    #[inline]
1417    pub fn wait_blocking(self) -> Status {
1418        self.0.wait_blocking()
1419    }
1420
1421    /// Waits until the work item is completed.
1422    #[inline]
1423    pub fn wait(&mut self) -> impl Future<Output = Status> {
1424        self.0.wait()
1425    }
1426
1427    /// Cancels the work item and asynchronously waits until it is removed from the work queue.
1428    #[inline]
1429    pub fn cancel(&mut self) -> impl Future<Output = ()> {
1430        self.0.cancel()
1431    }
1432}