kernel/hil/public_key_crypto/
signature.rs

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 HL: usize, const SL: 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; HL],
27        signature: &'static mut [u8; SL],
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/// - `HL`: The length in bytes of the hash.
37/// - `SL`: The length in bytes of the signature.
38pub trait SignatureVerify<'a, const HL: usize, const SL: usize> {
39    /// Set the client instance which will receive the `verification_done()`
40    /// callback.
41    fn set_verify_client(&self, client: &'a dyn ClientVerify<HL, SL>);
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; HL],
57        signature: &'static mut [u8; SL],
58    ) -> Result<(), (ErrorCode, &'static mut [u8; HL], &'static mut [u8; SL])>;
59}
60
61/// This trait provides callbacks for when the signing has completed.
62pub trait ClientSign<const HL: usize, const SL: usize> {
63    /// Called when the signing is complete.
64    ///
65    /// If the signing operation encounters an error, result will be a
66    /// `Result::Err()` specifying the ErrorCode. Otherwise, result will be
67    /// a `Result::Ok(())`.
68    ///
69    /// If signing operation did encounter errors `result` will be `Err()`
70    /// with an appropriate `ErrorCode`. Valid `ErrorCode`s include:
71    ///
72    /// - `CANCEL`: the operation was cancelled.
73    /// - `FAIL`: an internal failure.
74    fn signing_done(
75        &self,
76        result: Result<(), ErrorCode>,
77        hash: &'static mut [u8; HL],
78        signature: &'static mut [u8; SL],
79    );
80}
81
82/// Sign a message.
83///
84/// This is a generic interface, and it is up to the implementation as to the
85/// signing algorithm being used.
86///
87/// - `HL`: The length in bytes of the hash.
88/// - `SL`: The length in bytes of the signature.
89pub trait SignatureSign<'a, const HL: usize, const SL: usize> {
90    /// Set the client instance which will receive the `signing_done()`
91    /// callback.
92    fn set_sign_client(&self, client: &'a dyn ClientSign<HL, SL>);
93
94    /// Sign the given hash.
95    ///
96    /// If this returns `Ok(())`, then the `signing_done()` callback will
97    /// be called. If this returns `Err()`, no callback will be called.
98    ///
99    /// The valid `ErrorCode`s that can occur are:
100    ///
101    /// - `OFF`: the underlying digest engine is powered down and cannot be
102    ///   used.
103    /// - `BUSY`: there is an outstanding operation already in process, and the
104    ///   signing engine cannot accept another request.
105    fn sign(
106        &self,
107        hash: &'static mut [u8; HL],
108        signature: &'static mut [u8; SL],
109    ) -> Result<(), (ErrorCode, &'static mut [u8; HL], &'static mut [u8; SL])>;
110}
kernel/hil/public_key_crypto/signature.rs

kernel/hil/public_key_crypto/
signature.rs
