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 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}