kernel/hil/public_key_crypto/
signature.rs

Help
1// Licensed under the Apache License, Version 2.0 or the MIT License.
2// SPDX-License-Identifier: Apache-2.0 OR MIT
3// Copyright Tock Contributors 2024.
4
5//! Interface for verifying signatures.
6
7use crate::ErrorCode;
8
9/// This trait provides callbacks for when the verification has completed.
10pub trait ClientVerify<const HASH_LEN: usize, const SIGNATURE_LEN: usize> {
11    /// Called when the verification is complete.
12    ///
13    /// If the verification operation encounters an error, result will be a
14    /// `Result::Err()` specifying the ErrorCode. Otherwise, result will be a
15    /// `Result::Ok` set to `Ok(true)` if the signature was correctly verified
16    /// and `Ok(false)` otherwise.
17    ///
18    /// If verification operation did encounter errors `result` will be `Err()`
19    /// with an appropriate `ErrorCode`. Valid `ErrorCode`s include:
20    ///
21    /// - `CANCEL`: the operation was cancelled.
22    /// - `FAIL`: an internal failure.
23    fn verification_done(
24        &self,
25        result: Result<bool, ErrorCode>,
26        hash: &'static mut [u8; HASH_LEN],
27        signature: &'static mut [u8; SIGNATURE_LEN],
28    );
29}
30
31/// Verify a signature.
32///
33/// This is a generic interface, and it is up to the implementation as to the
34/// signature verification algorithm being used.
35///
36/// - `HASH_LEN`: The length in bytes of the hash.
37/// - `SIGNATURE_LEN`: The length in bytes of the signature.
38pub trait SignatureVerify<'a, const HASH_LEN: usize, const SIGNATURE_LEN: usize> {
39    /// Set the client instance which will receive the `verification_done()`
40    /// callback.
41    fn set_verify_client(&self, client: &'a dyn ClientVerify<HASH_LEN, SIGNATURE_LEN>);
42
43    /// Verify the signature matches the given hash.
44    ///
45    /// If this returns `Ok(())`, then the `verification_done()` callback will
46    /// be called. If this returns `Err()`, no callback will be called.
47    ///
48    /// The valid `ErrorCode`s that can occur are:
49    ///
50    /// - `OFF`: the underlying digest engine is powered down and cannot be
51    ///   used.
52    /// - `BUSY`: there is an outstanding operation already in process, and the
53    ///   verification engine cannot accept another request.
54    fn verify(
55        &self,
56        hash: &'static mut [u8; HASH_LEN],
57        signature: &'static mut [u8; SIGNATURE_LEN],
58    ) -> Result<
59        (),
60        (
61            ErrorCode,
62            &'static mut [u8; HASH_LEN],
63            &'static mut [u8; SIGNATURE_LEN],
64        ),
65    >;
66}
67
68/// This trait provides callbacks for when the signing has completed.
69pub trait ClientSign<const HL: usize, const SL: usize> {
70    /// Called when the signing is complete.
71    ///
72    /// If the signing operation encounters an error, result will be a
73    /// `Result::Err()` specifying the ErrorCode. Otherwise, result will be
74    /// a `Result::Ok(())`.
75    ///
76    /// If signing operation did encounter errors `result` will be `Err()`
77    /// with an appropriate `ErrorCode`. Valid `ErrorCode`s include:
78    ///
79    /// - `CANCEL`: the operation was cancelled.
80    /// - `FAIL`: an internal failure.
81    fn signing_done(
82        &self,
83        result: Result<(), ErrorCode>,
84        hash: &'static mut [u8; HL],
85        signature: &'static mut [u8; SL],
86    );
87}
88
89/// Sign a message.
90///
91/// This is a generic interface, and it is up to the implementation as to the
92/// signing algorithm being used.
93///
94/// - `HL`: The length in bytes of the hash.
95/// - `SL`: The length in bytes of the signature.
96pub trait SignatureSign<'a, const HL: usize, const SL: usize> {
97    /// Set the client instance which will receive the `signing_done()`
98    /// callback.
99    fn set_sign_client(&self, client: &'a dyn ClientSign<HL, SL>);
100
101    /// Sign the given hash.
102    ///
103    /// If this returns `Ok(())`, then the `signing_done()` callback will
104    /// be called. If this returns `Err()`, no callback will be called.
105    ///
106    /// The valid `ErrorCode`s that can occur are:
107    ///
108    /// - `OFF`: the underlying digest engine is powered down and cannot be
109    ///   used.
110    /// - `BUSY`: there is an outstanding operation already in process, and the
111    ///   signing engine cannot accept another request.
112    fn sign(
113        &self,
114        hash: &'static mut [u8; HL],
115        signature: &'static mut [u8; SL],
116    ) -> Result<(), (ErrorCode, &'static mut [u8; HL], &'static mut [u8; SL])>;
117}
kernel/hil/public_key_crypto/signature.rs

kernel/hil/public_key_crypto/
signature.rs
