kernel/hil/
hasher.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 2022.
4
5//! Interface for Hasher
6
7use crate::utilities::leasable_buffer::SubSlice;
8use crate::utilities::leasable_buffer::SubSliceMut;
9use crate::ErrorCode;
10
11/// Implement this trait and use `set_client()` in order to receive callbacks.
12///
13/// 'L' is the length of the 'u8' array to store the hash output.
14pub trait Client<const L: usize> {
15    /// This callback is called when the data has been added to the hash
16    /// engine.
17    /// On error or success `data` will contain a reference to the original
18    /// data supplied to `add_data()`.
19    /// The possible ErrorCodes are:
20    ///    - SIZE: The size of the `data` buffer is invalid
21    fn add_data_done(&self, result: Result<(), ErrorCode>, data: SubSlice<'static, u8>);
22
23    /// This callback is called when the data has been added to the hash
24    /// engine.
25    /// On error or success `data` will contain a reference to the original
26    /// data supplied to `add_mut_data()`.
27    /// The possible ErrorCodes are:
28    ///    - SIZE: The size of the `data` buffer is invalid
29    fn add_mut_data_done(&self, result: Result<(), ErrorCode>, data: SubSliceMut<'static, u8>);
30
31    /// This callback is called when a hash is computed.
32    /// On error or success `hash` will contain a reference to the original
33    /// data supplied to `run()`.
34    /// The possible ErrorCodes are:
35    ///    - SIZE: The size of the `data` buffer is invalid
36    fn hash_done(&self, result: Result<(), ErrorCode>, hash: &'static mut [u8; L]);
37}
38
39/// Computes a non-cryptographic hash over data
40///
41/// 'L' is the length of the 'u8' array to store the hash output.
42pub trait Hasher<'a, const L: usize> {
43    /// Set the client instance which will receive `hash_done()` and
44    /// `add_data_done()` callbacks.
45    /// This callback is called when the data has been added to the hash
46    /// engine.
47    /// The callback should follow the `Client` `add_data_done` callback.
48    fn set_client(&'a self, client: &'a dyn Client<L>);
49
50    /// Add data to the hash block. This is the data that will be used
51    /// for the hash function.
52    /// Returns the number of bytes parsed on success
53    /// There is no guarantee the data has been written until the `add_data_done()`
54    /// callback is fired.
55    /// On error the return value will contain a return code and the original data
56    /// The possible ErrorCodes are:
57    ///    - BUSY: The system is busy performing an operation. The caller should
58    ///      expect a callback
59    ///    - SIZE: The size of the `data` buffer is invalid
60    fn add_data(
61        &self,
62        data: SubSlice<'static, u8>,
63    ) -> Result<usize, (ErrorCode, SubSlice<'static, u8>)>;
64
65    /// Add data to the hash block. This is the data that will be used
66    /// for the hash function.
67    /// Returns the number of bytes parsed on success
68    /// There is no guarantee the data has been written until the `add_data_done()`
69    /// callback is fired.
70    /// On error the return value will contain a return code and the original data
71    /// The possible ErrorCodes are:
72    ///    - BUSY: The system is busy performing an operation. The caller should
73    ///      expect a callback
74    ///    - SIZE: The size of the `data` buffer is invalid
75    fn add_mut_data(
76        &self,
77        data: SubSliceMut<'static, u8>,
78    ) -> Result<usize, (ErrorCode, SubSliceMut<'static, u8>)>;
79
80    /// Request the implementation to generate a hash and stores the returned
81    /// hash in the memory location specified.
82    /// This doesn't return any data, instead the client needs to have
83    /// set a `hash_done` handler to determine when this is complete.
84    /// On error the return value will contain a return code and the original data
85    /// If there is data from the `add_data()` command asynchronously waiting to
86    /// be written it will be written before the operation starts.
87    /// The possible ErrorCodes are:
88    ///    - BUSY: The system is busy performing an operation. The caller should
89    ///      expect a callback
90    ///    - SIZE: The size of the `data` buffer is invalid
91    fn run(&'a self, hash: &'static mut [u8; L]) -> Result<(), (ErrorCode, &'static mut [u8; L])>;
92
93    /// Clear the internal state of the engine.
94    /// This won't clear the buffers provided to this API, that is up to the
95    /// user to clear.
96    fn clear_data(&self);
97}
98
99pub trait SipHash {
100    /// Optionally call before `Hasher::run()` to specify the keys used
101    /// The possible ErrorCodes are:
102    ///    - BUSY: The system is busy
103    ///    - ALREADY: An operation is already on going
104    ///    - INVAL: An invalid parameter was supplied
105    ///    - NOSUPPORT: The operation is not supported
106    fn set_keys(&self, k0: u64, k1: u64) -> Result<(), ErrorCode>;
107}
kernel/hil/hasher.rs

kernel/hil/
hasher.rs
