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}
kernel/hil/public_key_crypto/signature.rs

kernel/hil/public_key_crypto/
signature.rs
