aranya_crypto/ciphersuite/
mod.rs

1//!  - `AEAD`: Authenticated Encryption with Additional
2//!    Authenticated Data.  See [AEAD] and [RFC 5116].
3//!  - `Digital signature`: See [Signature].
4//!  - `encapsulate`: To encrypt cryptographic key material,
5//!    typically for use with an asymmetric algorithm. See [KEM].
6//!  - `HPKE`: Hybrid Public Key Encryption. See [HPKE].
7//!  - `KDF`: A Key Derivation Function. See [KDF].
8//!  - `KEM`: A Key Encapsulation Mechanism. See [KEM].
9//!  - `seal`: Synonymous with "encrypt."
10//!  - `open`: Synonymous with "decrypt."
11//!
12//! [AEAD]: https://en.wikipedia.org/wiki/Authenticated_encryption
13//! [HPKE]: https://www.rfc-editor.org/rfc/rfc9180.html
14//! [KDF]: https://en.wikipedia.org/wiki/Key_derivation_function
15//! [KEM]: https://en.wikipedia.org/wiki/Key_encapsulation_mechanism
16//! [RFC 5116]: https://www.rfc-editor.org/rfc/rfc5116
17//! [Signature]: https://en.wikipedia.org/wiki/Digital_signature
18
19mod ext;
20
21use spideroak_crypto::{
22    hash,
23    hpke::{HpkeAead, HpkeKdf, HpkeKem},
24    mac,
25    oid::Identified,
26    signer,
27    typenum::U32,
28};
29
30pub(crate) use crate::ciphersuite::ext::CipherSuiteExt;
31pub use crate::ciphersuite::ext::Oids;
32
33/// A marker trait for AEADs.
34pub trait Aead: HpkeAead + Identified {}
35
36impl<A: HpkeAead + Identified> Aead for A {}
37
38/// A marker trait for cryptographic hash functions.
39pub trait Hash: hash::Hash + Identified {}
40
41impl<H: hash::Hash + Identified> Hash for H {}
42
43/// A marker trait for key derivation functions.
44pub trait Kdf: HpkeKdf + Identified {}
45
46impl<K: HpkeKdf + Identified> Kdf for K {}
47
48/// A marker trait for key encapsulation mechanisms.
49pub trait Kem: HpkeKem + Identified {}
50
51impl<K: HpkeKem + Identified> Kem for K {}
52
53/// A marker trait for messaged authentication codes.
54pub trait Mac: mac::Mac + Identified {}
55
56impl<M: mac::Mac + Identified> Mac for M {}
57
58/// A marker trait for digital signatures.
59pub trait Signer: signer::Signer + Identified {}
60
61impl<S: signer::Signer + Identified> Signer for S {}
62
63/// The cryptographic primitives used by the cryptography engine.
64///
65/// # Warning
66///
67/// It is incredibly important to fully read the documentation
68/// for every single primitive as some primitives have very
69/// particular requirements. For example, implementations of
70/// [`Signer`] must reject non-canonical signatures. For ECDSA,
71/// this might mean rejecting `-s mod N`.
72///
73/// While the requirements were designed to help ensure safe
74/// defaults regardless of algorithm, it is still possible to
75/// choose algorithms (or implementations) that severely
76/// compromise the security of the engine. As such, we very
77/// highly recommend that only cryptographers or experienced
78/// cryptography engineers implement their own cipher suites.
79///
80/// Additionally, please test your implementation using the
81/// `test_util` module.
82pub trait CipherSuite {
83    /// OIDS contains the OIDs from the algorithms in the cipher
84    /// suite.
85    const OIDS: Oids<Self> = Oids::new();
86
87    /// See [`Aead`] for more information.
88    type Aead: Aead;
89    /// See [`Hash`] for more information.
90    type Hash: Hash<DigestSize = U32>;
91    /// See [`Kdf`] for more information.
92    type Kdf: Kdf;
93    /// See [`Kem`] for more information.
94    type Kem: Kem;
95    /// See [`Mac`] for more information.
96    type Mac: Mac;
97    /// See [`Signer`] for more information.
98    type Signer: Signer;
99}
100
101#[cfg(test)]
102mod tests {
103    mod rust {
104        use spideroak_crypto::{
105            oid::consts::DHKEM_P256_HKDF_SHA256,
106            rust::{self, Aes256Gcm, HkdfSha256, HkdfSha384, HmacSha512, P256, P384, Sha256},
107        };
108
109        use crate::{
110            kem_with_oid,
111            test_util::{TestCs, test_ciphersuite},
112        };
113
114        kem_with_oid! {
115            /// DHKEM(P256, HKDF-SHA256).
116            #[derive(Debug)]
117            struct DhKemP256HkdfSha256(rust::DhKemP256HkdfSha256) => DHKEM_P256_HKDF_SHA256
118        }
119
120        test_ciphersuite!(p256, TestCs<
121            Aes256Gcm,
122            Sha256,
123            HkdfSha256,
124            DhKemP256HkdfSha256,
125            HmacSha512,
126            P256,
127        >);
128        test_ciphersuite!(p384, TestCs<
129            Aes256Gcm,
130            Sha256,
131            HkdfSha384,
132            DhKemP256HkdfSha256, // DhKemP384HkdfSha384 does not exist
133            HmacSha512,
134            P384,
135        >);
136    }
137}
aranya_crypto/ciphersuite/mod.rs

aranya_crypto/ciphersuite/
mod.rs
