aranya-crypto 0.14.1

The Aranya Cryptography Engine
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137

//!  - `AEAD`: Authenticated Encryption with Additional
//!    Authenticated Data.  See [AEAD] and [RFC 5116].
//!  - `Digital signature`: See [Signature].
//!  - `encapsulate`: To encrypt cryptographic key material,
//!    typically for use with an asymmetric algorithm. See [KEM].
//!  - `HPKE`: Hybrid Public Key Encryption. See [HPKE].
//!  - `KDF`: A Key Derivation Function. See [KDF].
//!  - `KEM`: A Key Encapsulation Mechanism. See [KEM].
//!  - `seal`: Synonymous with "encrypt."
//!  - `open`: Synonymous with "decrypt."
//!
//! [AEAD]: https://en.wikipedia.org/wiki/Authenticated_encryption
//! [HPKE]: https://www.rfc-editor.org/rfc/rfc9180.html
//! [KDF]: https://en.wikipedia.org/wiki/Key_derivation_function
//! [KEM]: https://en.wikipedia.org/wiki/Key_encapsulation_mechanism
//! [RFC 5116]: https://www.rfc-editor.org/rfc/rfc5116
//! [Signature]: https://en.wikipedia.org/wiki/Digital_signature

mod ext;

use spideroak_crypto::{
    hash,
    hpke::{HpkeAead, HpkeKdf, HpkeKem},
    mac,
    oid::Identified,
    signer,
    typenum::U32,
};

pub(crate) use crate::ciphersuite::ext::CipherSuiteExt;
pub use crate::ciphersuite::ext::Oids;

/// A marker trait for AEADs.
pub trait Aead: HpkeAead + Identified {}

impl<A: HpkeAead + Identified> Aead for A {}

/// A marker trait for cryptographic hash functions.
pub trait Hash: hash::Hash + Identified {}

impl<H: hash::Hash + Identified> Hash for H {}

/// A marker trait for key derivation functions.
pub trait Kdf: HpkeKdf + Identified {}

impl<K: HpkeKdf + Identified> Kdf for K {}

/// A marker trait for key encapsulation mechanisms.
pub trait Kem: HpkeKem + Identified {}

impl<K: HpkeKem + Identified> Kem for K {}

/// A marker trait for messaged authentication codes.
pub trait Mac: mac::Mac + Identified {}

impl<M: mac::Mac + Identified> Mac for M {}

/// A marker trait for digital signatures.
pub trait Signer: signer::Signer + Identified {}

impl<S: signer::Signer + Identified> Signer for S {}

/// The cryptographic primitives used by the cryptography engine.
///
/// # Warning
///
/// It is incredibly important to fully read the documentation
/// for every single primitive as some primitives have very
/// particular requirements. For example, implementations of
/// [`Signer`] must reject non-canonical signatures. For ECDSA,
/// this might mean rejecting `-s mod N`.
///
/// While the requirements were designed to help ensure safe
/// defaults regardless of algorithm, it is still possible to
/// choose algorithms (or implementations) that severely
/// compromise the security of the engine. As such, we very
/// highly recommend that only cryptographers or experienced
/// cryptography engineers implement their own cipher suites.
///
/// Additionally, please test your implementation using the
/// `test_util` module.
pub trait CipherSuite {
    /// OIDS contains the OIDs from the algorithms in the cipher
    /// suite.
    const OIDS: Oids<Self> = Oids::new();

    /// See [`Aead`] for more information.
    type Aead: Aead;
    /// See [`Hash`] for more information.
    type Hash: Hash<DigestSize = U32>;
    /// See [`Kdf`] for more information.
    type Kdf: Kdf;
    /// See [`Kem`] for more information.
    type Kem: Kem;
    /// See [`Mac`] for more information.
    type Mac: Mac;
    /// See [`Signer`] for more information.
    type Signer: Signer;
}

#[cfg(test)]
mod tests {
    mod rust {
        use spideroak_crypto::{
            oid::consts::DHKEM_P256_HKDF_SHA256,
            rust::{self, Aes256Gcm, HkdfSha256, HkdfSha384, HmacSha512, P256, P384, Sha256},
        };

        use crate::{
            kem_with_oid,
            test_util::{TestCs, test_ciphersuite},
        };

        kem_with_oid! {
            /// DHKEM(P256, HKDF-SHA256).
            #[derive(Debug)]
            struct DhKemP256HkdfSha256(rust::DhKemP256HkdfSha256) => DHKEM_P256_HKDF_SHA256
        }

        test_ciphersuite!(p256, TestCs<
            Aes256Gcm,
            Sha256,
            HkdfSha256,
            DhKemP256HkdfSha256,
            HmacSha512,
            P256,
        >);
        test_ciphersuite!(p384, TestCs<
            Aes256Gcm,
            Sha256,
            HkdfSha384,
            DhKemP256HkdfSha256, // DhKemP384HkdfSha384 does not exist
            HmacSha512,
            P384,
        >);
    }
}