ytls_traits/
t_keys.rs

1//! yTLS Key related traits
2//! Implement to provide TLS1.3 Key Schedule per RFC 8446 s. 7.1
3//! The trait is split in order to provide typed triggers to clean
4/// up old secrets when not needed anymore beyond their purpose.
5
6//use crate::CryptoConfig;
7
8/// When context upgrades we need to store/load generated ap secrets
9pub trait SecretStore {
10    fn store_ap_client_key(&mut self, k: &[u8]) -> ();
11    fn store_ap_client_iv(&mut self, n: &[u8]) -> ();
12    fn store_ap_server_key(&mut self, k: &[u8]) -> ();
13    fn store_ap_server_iv(&mut self, n: &[u8]) -> ();
14
15    fn load_ap_client_key(&self) -> &[u8];
16    fn load_ap_client_iv(&self) -> &[u8];
17    fn load_ap_server_key(&self) -> &[u8];
18    fn load_ap_server_iv(&self) -> &[u8];
19}
20
21/// Initialize TLS1.3 Key Schedule
22pub trait Tls13KeyScheduleInit {
23    /// Init TLS1.3 Key Schedule with the given cryptography that includes Hkdf<Sha256> processor.
24    /// Select this if your AEAD cipher has _SHA256 suffix and no PSK
25    fn no_psk_with_crypto_and_sha256() -> impl Tls13KeyScheduleDerivedSha256;
26}
27
28/// TLS1.3 "derived" Key Schedule
29pub trait Tls13KeyScheduleDerivedSha256 {
30    /// Proceed to handshake secret with the given Input (1) x25519 shared secret
31    ///
32    /// ## Hash Input (2)
33    ///
34    /// The result hash of the combined ClientHello and ServerHello.
35    ///
36    /// ## Returns None upon incorrect input
37    ///
38    /// If the Input hash is incompatible with the initially provided hash
39    /// this will return None.
40    fn dh_x25519(
41        self,
42        _shared_secret: &[u8; 32],
43        _input_hash: &[u8; 32],
44    ) -> impl Tls13KeyScheduleHandshakeSha256;
45}
46
47/// TLS1.3 "handshake" Key Schedule
48/// # Note
49/// Input mutable key or iv input must be the same length as the used
50/// cipher suite relevant input secret key or iv.
51pub trait Tls13KeyScheduleHandshakeSha256 {
52    /// Expands Key for the Server AEAD sender.
53    fn handshake_server_key(&self, _key: &mut [u8]) -> ();
54    /// Expands Key for the Client AEAD sender.
55    fn handshake_client_key(&self, _key: &mut [u8]) -> ();
56    /// Expands Nonce / IV for the Server AEAD sender.
57    fn handshake_server_iv(&self, _iv: &mut [u8]) -> ();
58    /// Expands Nonce IV for the Client AEAD sender.
59    fn handshake_client_iv(&self, _iv: &mut [u8]) -> ();
60    /// Expands Key for the Client to finish Handshake
61    fn handshake_client_finished_key(&self, _key: &mut [u8]) -> ();
62    /// Expands Key for the Server to finish Handshake
63    fn handshake_server_finished_key(&self, _key: &mut [u8]) -> ();
64    fn into_secrets(self) -> ([u8; 32], [u8; 32], [u8; 32]);
65    fn from_secrets(
66        _shared_secret: [u8; 32],
67        _client_secret: [u8; 32],
68        _server_secret: [u8; 32],
69    ) -> Self;
70    /// Upon finishing handshake, proceed to Master Key schedule with the final hash of the hanshakes.
71    ///
72    /// ## Hash Input
73    ///
74    /// The complete hash result of all handshake messages from ClientHello to finished.
75    fn finished_handshake(self, _handshake_hash: &[u8; 32]) -> impl Tls13KeyScheduleApSha256;
76}
77
78/// TLS1.3 "Main" Key Schedule for Application Traffic post-handshake.
79/// # Note
80/// Input mutable key or iv input must be the same length as the used
81/// cipher suite relevant input secret key or iv.
82pub trait Tls13KeyScheduleApSha256 {
83    /// Expands Key for the Server AEAD sender.
84    fn application_server_key(&self, _key: &mut [u8]) -> ();
85    /// Expands Key for the Client AEAD sender.
86    fn application_client_key(&self, _key: &mut [u8]) -> ();
87    /// Expands IV for the Server AEAD sender.
88    fn application_server_iv(&self, _iv: &mut [u8]) -> ();
89    /// Expands IV for the Client AEAD sender.
90    fn application_client_iv(&self, _iv: &mut [u8]) -> ();
91}
92
93// TODO: Updated traffic keys
ytls_traits/t_keys.rs

ytls_traits/
t_keys.rs
