ytls_traits/
t_crypto.rs

1//! ytls Crypto traits
2
3//----------------------------------------------------------
4// Providers
5//----------------------------------------------------------
6
7#[doc(inline)]
8pub use rand_core::CryptoRng;
9
10/// Cryptography configuration is provied through implmenting
11/// this trait. Typically providers provide implementation or
12/// implementer can provide a mix of used primitives.
13pub trait CryptoConfig {
14    type PrkError;
15    // TODO: cfg-gate supported hashers
16    type Hasher: CryptoSha256TranscriptProcessor;
17    type X25519: CryptoX25519Processor;
18    /// Provide the concrete ECDHE providing the X25519
19    fn ecdhe_x25519<R: CryptoRng>(_: &mut R) -> Self::X25519;
20    /// Provide the concrete hasher containing SHA256 hasher
21    fn hasher_sha256() -> Self::Hasher;
22    /// ECDSA secp256p1 Signature processor
23    fn sign_p256_init(_key: &[u8]) -> Option<impl CryptoSignerP256Processor>;
24    /// AEAD ChaCha20Poly1305 with Key and Nonce / IV
25    fn aead_chaha20poly1305(_key: &[u8; 32]) -> impl CryptoChaCha20Poly1305Processor;
26    /// Hkdf256 Sha256 from strong pre-existing prk
27    fn hkdf_sha256_from_prk(
28        _prk: &[u8],
29    ) -> Result<impl CryptoSha256HkdfGenProcessor, Self::PrkError>;
30    /// Provide the configured Hkdf Sha256 impl
31    fn hkdf_sha256_init() -> impl CryptoSha256HkdfExtractProcessor;
32    /// Provide the configured Hmac Sha384 impl
33    fn hmac_sha384_init_with_key(_key: &[u8; 48]) -> impl CryptoSha384HmacProcessor;
34    /// Provide the configured Hmac Sha256 impl
35    fn hmac_sha256_init_with_key(_key: &[u8; 32]) -> impl CryptoSha256HmacProcessor;
36    /// Provide the configured SHA256 Hasher impl
37    fn sha256_init() -> impl CryptoSha256TranscriptProcessor;
38    /// Provide the configured SHA384 Hasher impl
39    fn sha384_init() -> impl CryptoSha384TranscriptProcessor;
40    /// Provide the configured Ephemeral X25519 impl
41    fn x25519_init<R: CryptoRng>(&mut self, _: &mut R) -> impl CryptoX25519Processor;
42}
43
44/// ECDSA Signature Processor secp256p1
45pub trait CryptoSignerP256Processor {
46    /// Sign the content and indicate the output length of the signature if the
47    /// output buffer was long enough.
48    /// The output is DER encoded raw bytes as supplied through certificate verify.
49    /// The success of the operation always returns Some(written)
50    ///
51    /// ## Warning
52    ///
53    /// In case the output buffer is too small the result is None and must be
54    /// handled by increasing the output buffer size and retried.
55    ///
56    /// Given the output is variable sized, the output must be always
57    /// cut to size with the indicated return length.
58    #[must_use]
59    fn sign_p256(&self, _content: &[u8], _output: &mut [u8]) -> Option<usize>;
60}
61
62/// HMAC (Hash-based Message Authentication Code) SHA256.
63/// @At Handshake Finished
64pub trait CryptoSha256HmacProcessor {
65    /// Update HMAC based on data of content
66    fn hmac_sha256_update(&mut self, _content: &[u8]) -> ();
67    /// Fork from the current
68    fn hmac_sha256_fork(&self) -> Self;
69    /// Finalize HMAC
70    fn hmac_sha256_finalize(self) -> [u8; 32];
71}
72
73/// HMAC (Hash-based Message Authentication Code) SHA384.
74/// @At Handshake Finished
75pub trait CryptoSha384HmacProcessor {
76    /// Update HMAC based on data of content
77    fn hmac_sha384_update(&mut self, _content: &[u8]) -> ();
78    /// Fork from the current
79    fn hmac_sha384_fork(&self) -> Self;
80    /// Finalize HMAC
81    fn hmac_sha384_finalize(self) -> [u8; 48];
82}
83
84/// HKDF (Hashing Key Derivation Function) Extract Processor
85pub trait CryptoSha256HkdfExtractProcessor {
86    /// HKDF Using SHA256
87    fn hkdf_sha256_extract(
88        &self,
89        _salt: Option<&[u8]>,
90        _ikm: &[u8],
91    ) -> ([u8; 32], impl CryptoSha256HkdfGenProcessor);
92}
93
94/// HKDF Gen Processor, e.g. to Expand
95pub trait CryptoSha256HkdfGenProcessor {
96    /// Associated error
97    type Error;
98    /// HKDF Using SHA256.
99    fn hkdf_sha256_expand(&self, _info: &[u8], _okm: &mut [u8]) -> Result<(), Self::Error>;
100}
101
102/// X25519 processor used to calculate the shared secret with
103/// the given input public key and returning the shared secret.
104pub trait CryptoX25519Processor {
105    /// Provide the associated public key
106    fn x25519_public_key(&self) -> [u8; 32];
107    /// Typically performns Diffie Hellman with the given public key
108    fn x25519_shared_secret(self, _pub_key: &[u8; 32]) -> [u8; 32];
109}
110
111/// Transcript processor used to hash handshakes.
112/// Typically implemented by the crypto provider.
113pub trait CryptoSha256TranscriptProcessor {
114    /// Update the SHA256 Transcript with the given data
115    fn sha256_update(&mut self, _: &[u8]) -> ();
116    /// Clone ourselves
117    fn sha256_fork(&self) -> Self;
118    /// Finalize the current SHA384 digest
119    fn sha256_finalize(self) -> [u8; 32];
120}
121
122/// Transcript processor used to hash handshakes.
123/// Typically implemented by the crypto provider.
124pub trait CryptoSha384TranscriptProcessor {
125    /// Update the SHA384 Transcript with the given data
126    fn sha384_update(&mut self, _: &[u8]) -> ();
127    /// Finalize the current SHA384 digest
128    fn sha384_finalize(self) -> [u8; 48];
129}
130
131#[derive(Debug)]
132pub enum AeadError {
133    Opaque,
134}
135
136/// ChaCha20Poly1305 AEAD Processor
137pub trait CryptoChaCha20Poly1305Processor {
138    fn encrypt_in_place(
139        &self,
140        _nonce: &[u8; 12],
141        _additional_data: &[u8],
142        _to_encrypt: &mut [u8],
143    ) -> Result<[u8; 16], AeadError>;
144    fn decrypt_in_place(
145        &self,
146        _nonce: &[u8; 12],
147        _additional_data: &[u8],
148        _to_decrypt: &mut [u8],
149        _tag: &[u8; 16],
150    ) -> Result<(), AeadError>;
151}
ytls_traits/t_crypto.rs

ytls_traits/
t_crypto.rs
