rustls/crypto/
tls12.rs

1use alloc::boxed::Box;
2
3use pki_types::FipsStatus;
4
5use super::hmac;
6use super::kx::ActiveKeyExchange;
7use crate::enums::ProtocolVersion;
8use crate::error::Error;
9
10/// Implements [`Prf`] using a [`hmac::Hmac`].
11#[expect(clippy::exhaustive_structs)]
12pub struct PrfUsingHmac<'a>(pub &'a dyn hmac::Hmac);
13
14impl Prf for PrfUsingHmac<'_> {
15    fn for_key_exchange(
16        &self,
17        output: &mut [u8; 48],
18        kx: Box<dyn ActiveKeyExchange>,
19        peer_pub_key: &[u8],
20        label: &[u8],
21        seed: &[u8],
22    ) -> Result<(), Error> {
23        prf(
24            output,
25            self.0
26                .with_key(
27                    kx.complete_for_tls_version(peer_pub_key, ProtocolVersion::TLSv1_2)?
28                        .secret_bytes(),
29                )
30                .as_ref(),
31            label,
32            seed,
33        );
34        Ok(())
35    }
36
37    fn new_secret(&self, secret: &[u8; 48]) -> Box<dyn PrfSecret> {
38        Box::new(PrfSecretUsingHmac(self.0.with_key(secret)))
39    }
40}
41
42struct PrfSecretUsingHmac(Box<dyn hmac::Key>);
43
44impl PrfSecret for PrfSecretUsingHmac {
45    fn prf(&self, output: &mut [u8], label: &[u8], seed: &[u8]) {
46        prf(output, &*self.0, label, seed)
47    }
48}
49
50/// An instantiation of the TLS1.2 PRF with a specific, implicit hash function.
51///
52/// See the definition in [RFC5246 section 5](https://www.rfc-editor.org/rfc/rfc5246#section-5).
53///
54/// See [`PrfUsingHmac`] as a route to implementing this trait with just
55/// an implementation of [`hmac::Hmac`].
56pub trait Prf: Send + Sync {
57    /// Computes `PRF(secret, label, seed)` using the secret from a completed key exchange.
58    ///
59    /// Completes the given key exchange, and then uses the resulting shared secret
60    /// to compute the PRF, writing the result into `output`.
61    ///
62    /// The caller guarantees that `label`, `seed` are non-empty. The caller makes no
63    /// guarantees about the contents of `peer_pub_key`. It must be validated by
64    /// [`ActiveKeyExchange::complete`].
65    fn for_key_exchange(
66        &self,
67        output: &mut [u8; 48],
68        kx: Box<dyn ActiveKeyExchange>,
69        peer_pub_key: &[u8],
70        label: &[u8],
71        seed: &[u8],
72    ) -> Result<(), Error>;
73
74    /// Returns an object that can compute `PRF(secret, label, seed)` with
75    /// the same `master_secret`.
76    ///
77    /// This object can amortize any preprocessing needed on `master_secret` over
78    /// several `PRF(...)` calls.
79    fn new_secret(&self, master_secret: &[u8; 48]) -> Box<dyn PrfSecret>;
80
81    /// Return the FIPS validation status of this implementation.
82    fn fips(&self) -> FipsStatus {
83        FipsStatus::Unvalidated
84    }
85}
86
87/// An instantiation of the TLS1.2 PRF with a fixed hash function and master secret.
88pub trait PrfSecret: Send + Sync {
89    /// Computes `PRF(secret, label, seed)`, writing the result into `output`.
90    ///
91    /// `secret` is implicit in this object; see [`Prf::new_secret`].
92    ///
93    /// The caller guarantees that `label` and `seed` are non-empty.
94    fn prf(&self, output: &mut [u8], label: &[u8], seed: &[u8]);
95}
96
97#[doc(hidden)]
98pub fn prf(out: &mut [u8], hmac_key: &dyn hmac::Key, label: &[u8], seed: &[u8]) {
99    let mut previous_a: Option<hmac::Tag> = None;
100
101    let chunk_size = hmac_key.tag_len();
102    for chunk in out.chunks_mut(chunk_size) {
103        let a_i = match previous_a {
104            // A(0) = HMAC_hash(secret, label + seed)
105            None => hmac_key.sign(&[label, seed]),
106            // A(i) = HMAC_hash(secret, A(i - 1))
107            Some(previous_a) => hmac_key.sign(&[previous_a.as_ref()]),
108        };
109
110        // P_hash[i] = HMAC_hash(secret, A(i) + label + seed)
111        let p_term = hmac_key.sign(&[a_i.as_ref(), label, seed]);
112        chunk.copy_from_slice(&p_term.as_ref()[..chunk.len()]);
113
114        previous_a = Some(a_i);
115    }
116}
rustls/crypto/tls12.rs

rustls/crypto/
tls12.rs
