Skip to main content

embedded_cal_examples/
lib.rs

1// SPDX-License-Identifier: MIT OR Apache-2.0
2// SPDX-FileCopyrightText: Inria-AIO, Cryspen, and Christian Amsüss
3#![no_std]
4//! Examples that run some cryptographic operations.
5//!
6//! This is not rigorous testing, but a collection of functions that serve both as a quick "how to
7//! use" example and as a quick sanity check.
8
9use embedded_cal::accessor::*;
10use embedded_cal::*;
11
12use defmt_or_log::wrappers::Hex;
13use defmt_or_log::*;
14
15/// Shows a brief note on which implementations is being used, and then runs all other `show_*`
16/// functions in this module.
17pub fn show_examples(cal: &mut impl embedded_cal::Cal) {
18    info!(
19        "Running examples on a Cal of type {}",
20        core::any::type_name_of_val(&cal)
21    );
22
23    show_sha256_example(cal);
24
25    show_ecdh_example(cal);
26
27    show_aead_tests(cal);
28}
29
30/// Hashes a "hello world" string with the SHA-256 hash, if available.
31pub fn show_sha256_example(cal: &mut impl embedded_cal::Cal) {
32    let sha256 = HashAlgorithm::from_ni_name("sha-256");
33    if let Some(sha256) = sha256 {
34        let hash_me = "hello world";
35        let hashed = cal.hash().hash(sha256, hash_me.as_bytes());
36        info!(
37            "Computed SHA-256 hash of {:?} (encoded in ASCII); hash is {}",
38            hash_me,
39            Hex(hashed.as_ref())
40        );
41    } else {
42        warn!("Skipping hash demo: Suite does not support SHA-256");
43    }
44}
45
46/// Selects a key from a list of a peer's identity keys (based on the Cal's supported curves), and
47/// runs static-ephemeral Diffie-Hellman on it.
48// See https://github.com/lake-rs/embedded-cal/issues/131 on why this needs a full generic rather
49// than just an impl.
50pub fn show_ecdh_example<C: embedded_cal::Cal>(cal: &mut C) {
51    info!(
52        "Looking to find a matching ECDH curve for Diffie-Hellman key establishment based on a set of public key options."
53    );
54    // In an actual protocol, these could be public static keys offered by the peer.
55    let peer_keys = [
56        (1, &b"the p256 key offered by the peer"[..]),
57        (4, &b"if anyone finds pivkey were lost"[..]),
58        (
59            5,
60            &b"because these are obviously not pubkeys from real secrts"[..],
61        ),
62    ];
63
64    for (crvnum, peer_pub) in peer_keys.iter().rev() {
65        let Some(crv) = DhAlgorithmOf::<C>::from_cose_ecdh(*crvnum) else {
66            continue;
67        };
68        info!("Agreeing to use curve {}", crvnum);
69
70        let Ok(peer_pub) = cal.dh().import_publickey_bytes(crv.clone(), peer_pub) else {
71            error!("Peer's public key failed to load");
72            return;
73        };
74        let private = cal.dh().generate(crv);
75        let our_pub = cal.dh().public_key(&private);
76        let our_pub = cal.dh().export_publickey_bytes(&our_pub);
77        info!("Public part of our ephemeral key is {}", Hex(our_pub));
78        let secret = cal
79            .dh()
80            .shared_secret(&private, &peer_pub)
81            .expect("Curves match by construction");
82        let secret = cal.dh().raw_secret_bytes(&secret);
83        info!("Shared secret with that peer is {}", Hex(secret));
84
85        return;
86    }
87
88    warn!("No matching ECDH algorithm found.");
89}
90
91/// Runs through AEAD test vectors for some known algorithms
92pub fn show_aead_tests<C: embedded_cal::Cal>(cal: &mut C) {
93    let aead_algs = [
94        (
95            1,
96            embedded_cal_testvectors::aead::aes_gcm::test_128 as fn(&mut C),
97        ),
98        (
99            3,
100            embedded_cal_testvectors::aead::aes_gcm::test_256 as fn(&mut C),
101        ),
102        (
103            10,
104            embedded_cal_testvectors::aead::aes_ccm::test_16_64_128 as fn(&mut C),
105        ),
106        (
107            11,
108            embedded_cal_testvectors::aead::aes_ccm::test_16_64_256 as fn(&mut C),
109        ),
110    ];
111    let mut any = false;
112    for (algnum, fun) in aead_algs {
113        let Some(alg): Option<AeadAlgorithmOf<C>> = AeadAlgorithm::from_cose_number(algnum) else {
114            continue;
115        };
116        any = true;
117
118        info!(
119            "Running AEAD test vectors of COSE algorithm {} ({:?})",
120            algnum,
121            Debug2Format(&alg)
122        );
123        fun(cal);
124    }
125    if any {
126        info!("All AEAD tests passed.");
127    } else {
128        warn!("No AEAD algorithms for which tests cases are known are supproted by the cal.");
129    }
130}