embedded_cal_libcrux/lib.rs
1// SPDX-License-Identifier: MIT OR Apache-2.0
2// SPDX-FileCopyrightText: Inria-AIO, Cryspen, and Christian Amsüss
3//! libcrux-sha2 backed SHA-256, SHA-3, and AES-CCM/GCM, plus plumbing to extend any hardware-backed [`Cal`] with it.
4//!
5//! ## Secret Independence Checking
6//!
7//! The embedded-cal libcrux provider provides a libcrux-iot backed SHA-3 implementation that performs secret
8//! independence checking via the [libcrux-secrets][ls] crate. The secret independence checking of libcrux-secrets
9//! is performed via the Rust type system. By enabling the cargo feature `check-secret-independence` of the
10//! embedded-cal-libcrux crate, you can re-prove that the SHA-3 is indeed secret
11//! independent on the source code level.
12//!
13//! To use a SHA-3 digest as a [`libcrux-secrets::U8`][U8] type, you can call the [`HashResult::as_classified`] method.
14//! Note that currently only the `Sha3` variants are using the [libcrux-secrets][ls] crate.
15//! This can beneficial when, e.g., interacting with other libcrux APIs that require libcrux-secrets type
16//! to make use of the `check-secret-independence` feature.
17//!
18//! <div class="warning">
19//!
20//! The `check-secret-independence` feature is not intended to be enabled unconditionally.
21//! You should only enable it locally/in CI.
22//!
23//! </div>
24//!
25//! [ls]: https://docs.rs/libcrux-secrets/latest/libcrux_secrets/
26//! [U8]: https://docs.rs/libcrux-secrets/latest/libcrux_secrets/fn.U8.html
27#![no_std]
28
29use embedded_cal::{Cal, accessor::*, plumbing::Plumbing};
30use libcrux_sha2::Digest;
31
32mod aead;
33mod dh;
34mod hash;
35mod rng;
36
37#[cfg(feature = "standalone")]
38mod standalone;
39
40#[cfg(feature = "standalone")]
41pub use standalone::{Standalone, StandaloneConfig};
42
43pub use hash::HashResult;
44
45pub trait ExtenderConfig {
46 // Currently we could also just have a Base in the generic and do not use Plumbing, but we
47 // *will* use it in the future, and that will need more options, so this is reusing the design
48 // of -software-demo even though there is no immediate benefit.
49 // Base needs to implement the Infallible CryptoRng trait as the `DhProvider::generate_visible`
50 // method is infallible and can't return an Rng failure.
51 type Base: Cal + Plumbing + rand_core::CryptoRng;
52}
53
54pub struct Extender<EC: ExtenderConfig>(EC::Base);
55
56impl<EC: ExtenderConfig> Extender<EC> {
57 pub fn new(base: EC::Base) -> Self {
58 Self(base)
59 }
60}
61
62impl<EC: ExtenderConfig> Cal for Extender<EC> {
63 type DhProvider = Self;
64 type AeadProvider = Self;
65 type HashProvider = Self;
66 // FIXME: This should just be provided as well.
67 type HmacProvider = HmacProviderOf<EC::Base>;
68
69 fn dh(&mut self) -> &mut Self::DhProvider {
70 self
71 }
72 fn aead(&mut self) -> &mut Self::AeadProvider {
73 self
74 }
75 fn hash(&mut self) -> &mut Self::HashProvider {
76 self
77 }
78 fn hmac(&mut self) -> &mut Self::HmacProvider {
79 self.0.hmac()
80 }
81}