rustls/crypto/ring/
tls13.rs

1use alloc::boxed::Box;
2
3use super::ring_like::hkdf::KeyType;
4use super::ring_like::{aead, hkdf, hmac};
5use crate::crypto;
6use crate::crypto::cipher::{
7    AeadKey, InboundOpaqueMessage, Iv, MessageDecrypter, MessageEncrypter, Nonce,
8    Tls13AeadAlgorithm, UnsupportedOperationError, make_tls13_aad,
9};
10use crate::crypto::tls13::{Hkdf, HkdfExpander, OkmBlock, OutputLengthError};
11use crate::enums::{CipherSuite, ContentType, ProtocolVersion};
12use crate::error::Error;
13use crate::msgs::message::{
14    InboundPlainMessage, OutboundOpaqueMessage, OutboundPlainMessage, PrefixedPayload,
15};
16use crate::suites::{CipherSuiteCommon, ConnectionTrafficSecrets};
17use crate::tls13::Tls13CipherSuite;
18use crate::version::TLS13_VERSION;
19
20/// The TLS1.3 ciphersuite TLS_CHACHA20_POLY1305_SHA256
21pub static TLS13_CHACHA20_POLY1305_SHA256: &Tls13CipherSuite = &Tls13CipherSuite {
22    common: CipherSuiteCommon {
23        suite: CipherSuite::TLS13_CHACHA20_POLY1305_SHA256,
24        hash_provider: &super::hash::SHA256,
25        // ref: <https://www.ietf.org/archive/id/draft-irtf-cfrg-aead-limits-08.html#section-5.2.1>
26        confidentiality_limit: u64::MAX,
27    },
28    protocol_version: TLS13_VERSION,
29    hkdf_provider: &RingHkdf(hkdf::HKDF_SHA256, hmac::HMAC_SHA256),
30    aead_alg: &Chacha20Poly1305Aead(AeadAlgorithm(&aead::CHACHA20_POLY1305)),
31    quic: Some(&super::quic::KeyBuilder {
32        packet_alg: &aead::CHACHA20_POLY1305,
33        header_alg: &aead::quic::CHACHA20,
34        // ref: <https://datatracker.ietf.org/doc/html/rfc9001#section-6.6>
35        confidentiality_limit: u64::MAX,
36        // ref: <https://datatracker.ietf.org/doc/html/rfc9001#section-6.6>
37        integrity_limit: 1 << 36,
38    }),
39};
40
41/// The TLS1.3 ciphersuite TLS_AES_256_GCM_SHA384
42pub static TLS13_AES_256_GCM_SHA384: &Tls13CipherSuite = &Tls13CipherSuite {
43    common: CipherSuiteCommon {
44        suite: CipherSuite::TLS13_AES_256_GCM_SHA384,
45        hash_provider: &super::hash::SHA384,
46        confidentiality_limit: 1 << 24,
47    },
48    protocol_version: TLS13_VERSION,
49    hkdf_provider: &RingHkdf(hkdf::HKDF_SHA384, hmac::HMAC_SHA384),
50    aead_alg: &Aes256GcmAead(AeadAlgorithm(&aead::AES_256_GCM)),
51    quic: Some(&super::quic::KeyBuilder {
52        packet_alg: &aead::AES_256_GCM,
53        header_alg: &aead::quic::AES_256,
54        // ref: <https://datatracker.ietf.org/doc/html/rfc9001#section-b.1.1>
55        confidentiality_limit: 1 << 23,
56        // ref: <https://datatracker.ietf.org/doc/html/rfc9001#section-b.1.2>
57        integrity_limit: 1 << 52,
58    }),
59};
60
61/// The TLS1.3 ciphersuite TLS_AES_128_GCM_SHA256
62pub static TLS13_AES_128_GCM_SHA256: &Tls13CipherSuite = &Tls13CipherSuite {
63    common: CipherSuiteCommon {
64        suite: CipherSuite::TLS13_AES_128_GCM_SHA256,
65        hash_provider: &super::hash::SHA256,
66        confidentiality_limit: 1 << 24,
67    },
68    protocol_version: TLS13_VERSION,
69    hkdf_provider: &RingHkdf(hkdf::HKDF_SHA256, hmac::HMAC_SHA256),
70    aead_alg: &Aes128GcmAead(AeadAlgorithm(&aead::AES_128_GCM)),
71    quic: Some(&super::quic::KeyBuilder {
72        packet_alg: &aead::AES_128_GCM,
73        header_alg: &aead::quic::AES_128,
74        // ref: <https://datatracker.ietf.org/doc/html/rfc9001#section-b.1.1>
75        confidentiality_limit: 1 << 23,
76        // ref: <https://datatracker.ietf.org/doc/html/rfc9001#section-b.1.2>
77        integrity_limit: 1 << 52,
78    }),
79};
80
81struct Chacha20Poly1305Aead(AeadAlgorithm);
82
83impl Tls13AeadAlgorithm for Chacha20Poly1305Aead {
84    fn encrypter(&self, key: AeadKey, iv: Iv) -> Box<dyn MessageEncrypter> {
85        self.0.encrypter(key, iv)
86    }
87
88    fn decrypter(&self, key: AeadKey, iv: Iv) -> Box<dyn MessageDecrypter> {
89        self.0.decrypter(key, iv)
90    }
91
92    fn key_len(&self) -> usize {
93        self.0.key_len()
94    }
95
96    fn extract_keys(
97        &self,
98        key: AeadKey,
99        iv: Iv,
100    ) -> Result<ConnectionTrafficSecrets, UnsupportedOperationError> {
101        Ok(ConnectionTrafficSecrets::Chacha20Poly1305 { key, iv })
102    }
103
104    fn fips(&self) -> bool {
105        false // chacha20poly1305 not FIPS approved
106    }
107}
108
109struct Aes256GcmAead(AeadAlgorithm);
110
111impl Tls13AeadAlgorithm for Aes256GcmAead {
112    fn encrypter(&self, key: AeadKey, iv: Iv) -> Box<dyn MessageEncrypter> {
113        self.0.encrypter(key, iv)
114    }
115
116    fn decrypter(&self, key: AeadKey, iv: Iv) -> Box<dyn MessageDecrypter> {
117        self.0.decrypter(key, iv)
118    }
119
120    fn key_len(&self) -> usize {
121        self.0.key_len()
122    }
123
124    fn extract_keys(
125        &self,
126        key: AeadKey,
127        iv: Iv,
128    ) -> Result<ConnectionTrafficSecrets, UnsupportedOperationError> {
129        Ok(ConnectionTrafficSecrets::Aes256Gcm { key, iv })
130    }
131
132    fn fips(&self) -> bool {
133        super::fips()
134    }
135}
136
137struct Aes128GcmAead(AeadAlgorithm);
138
139impl Tls13AeadAlgorithm for Aes128GcmAead {
140    fn encrypter(&self, key: AeadKey, iv: Iv) -> Box<dyn MessageEncrypter> {
141        self.0.encrypter(key, iv)
142    }
143
144    fn decrypter(&self, key: AeadKey, iv: Iv) -> Box<dyn MessageDecrypter> {
145        self.0.decrypter(key, iv)
146    }
147
148    fn key_len(&self) -> usize {
149        self.0.key_len()
150    }
151
152    fn extract_keys(
153        &self,
154        key: AeadKey,
155        iv: Iv,
156    ) -> Result<ConnectionTrafficSecrets, UnsupportedOperationError> {
157        Ok(ConnectionTrafficSecrets::Aes128Gcm { key, iv })
158    }
159
160    fn fips(&self) -> bool {
161        super::fips()
162    }
163}
164
165// common encrypter/decrypter/key_len items for above Tls13AeadAlgorithm impls
166struct AeadAlgorithm(&'static aead::Algorithm);
167
168impl AeadAlgorithm {
169    fn encrypter(&self, key: AeadKey, iv: Iv) -> Box<dyn MessageEncrypter> {
170        // safety: the caller arranges that `key` is `key_len()` in bytes, so this unwrap is safe.
171        Box::new(Tls13MessageEncrypter {
172            enc_key: aead::LessSafeKey::new(aead::UnboundKey::new(self.0, key.as_ref()).unwrap()),
173            iv,
174        })
175    }
176
177    fn decrypter(&self, key: AeadKey, iv: Iv) -> Box<dyn MessageDecrypter> {
178        // safety: the caller arranges that `key` is `key_len()` in bytes, so this unwrap is safe.
179        Box::new(Tls13MessageDecrypter {
180            dec_key: aead::LessSafeKey::new(aead::UnboundKey::new(self.0, key.as_ref()).unwrap()),
181            iv,
182        })
183    }
184
185    fn key_len(&self) -> usize {
186        self.0.key_len()
187    }
188}
189
190struct Tls13MessageEncrypter {
191    enc_key: aead::LessSafeKey,
192    iv: Iv,
193}
194
195struct Tls13MessageDecrypter {
196    dec_key: aead::LessSafeKey,
197    iv: Iv,
198}
199
200impl MessageEncrypter for Tls13MessageEncrypter {
201    fn encrypt(
202        &mut self,
203        msg: OutboundPlainMessage<'_>,
204        seq: u64,
205    ) -> Result<OutboundOpaqueMessage, Error> {
206        let total_len = self.encrypted_payload_len(msg.payload.len());
207        let mut payload = PrefixedPayload::with_capacity(total_len);
208
209        let nonce = aead::Nonce::assume_unique_for_key(Nonce::new(&self.iv, seq).0);
210        let aad = aead::Aad::from(make_tls13_aad(total_len));
211        payload.extend_from_chunks(&msg.payload);
212        payload.extend_from_slice(&msg.typ.to_array());
213
214        self.enc_key
215            .seal_in_place_append_tag(nonce, aad, &mut payload)
216            .map_err(|_| Error::EncryptError)?;
217
218        Ok(OutboundOpaqueMessage::new(
219            ContentType::ApplicationData,
220            // Note: all TLS 1.3 application data records use TLSv1_2 (0x0303) as the legacy record
221            // protocol version, see https://www.rfc-editor.org/rfc/rfc8446#section-5.1
222            ProtocolVersion::TLSv1_2,
223            payload,
224        ))
225    }
226
227    fn encrypted_payload_len(&self, payload_len: usize) -> usize {
228        payload_len + 1 + self.enc_key.algorithm().tag_len()
229    }
230}
231
232impl MessageDecrypter for Tls13MessageDecrypter {
233    fn decrypt<'a>(
234        &mut self,
235        mut msg: InboundOpaqueMessage<'a>,
236        seq: u64,
237    ) -> Result<InboundPlainMessage<'a>, Error> {
238        let payload = &mut msg.payload;
239        if payload.len() < self.dec_key.algorithm().tag_len() {
240            return Err(Error::DecryptError);
241        }
242
243        let nonce = aead::Nonce::assume_unique_for_key(Nonce::new(&self.iv, seq).0);
244        let aad = aead::Aad::from(make_tls13_aad(payload.len()));
245        let plain_len = self
246            .dec_key
247            .open_in_place(nonce, aad, payload)
248            .map_err(|_| Error::DecryptError)?
249            .len();
250
251        payload.truncate(plain_len);
252        msg.into_tls13_unpadded_message()
253    }
254}
255
256struct RingHkdf(hkdf::Algorithm, hmac::Algorithm);
257
258impl Hkdf for RingHkdf {
259    fn extract_from_zero_ikm(&self, salt: Option<&[u8]>) -> Box<dyn HkdfExpander> {
260        let zeroes = [0u8; OkmBlock::MAX_LEN];
261        let salt = match salt {
262            Some(salt) => salt,
263            None => &zeroes[..self.0.len()],
264        };
265        Box::new(RingHkdfExpander {
266            alg: self.0,
267            prk: hkdf::Salt::new(self.0, salt).extract(&zeroes[..self.0.len()]),
268        })
269    }
270
271    fn extract_from_secret(&self, salt: Option<&[u8]>, secret: &[u8]) -> Box<dyn HkdfExpander> {
272        let zeroes = [0u8; OkmBlock::MAX_LEN];
273        let salt = match salt {
274            Some(salt) => salt,
275            None => &zeroes[..self.0.len()],
276        };
277        Box::new(RingHkdfExpander {
278            alg: self.0,
279            prk: hkdf::Salt::new(self.0, salt).extract(secret),
280        })
281    }
282
283    fn expander_for_okm(&self, okm: &OkmBlock) -> Box<dyn HkdfExpander> {
284        Box::new(RingHkdfExpander {
285            alg: self.0,
286            prk: hkdf::Prk::new_less_safe(self.0, okm.as_ref()),
287        })
288    }
289
290    fn hmac_sign(&self, key: &OkmBlock, message: &[u8]) -> crypto::hmac::Tag {
291        crypto::hmac::Tag::new(hmac::sign(&hmac::Key::new(self.1, key.as_ref()), message).as_ref())
292    }
293
294    fn fips(&self) -> bool {
295        super::fips()
296    }
297}
298
299struct RingHkdfExpander {
300    alg: hkdf::Algorithm,
301    prk: hkdf::Prk,
302}
303
304impl HkdfExpander for RingHkdfExpander {
305    fn expand_slice(&self, info: &[&[u8]], output: &mut [u8]) -> Result<(), OutputLengthError> {
306        self.prk
307            .expand(info, Len(output.len()))
308            .and_then(|okm| okm.fill(output))
309            .map_err(|_| OutputLengthError)
310    }
311
312    fn expand_block(&self, info: &[&[u8]]) -> OkmBlock {
313        let mut buf = [0u8; OkmBlock::MAX_LEN];
314        let output = &mut buf[..self.hash_len()];
315        self.prk
316            .expand(info, Len(output.len()))
317            .and_then(|okm| okm.fill(output))
318            .unwrap();
319        OkmBlock::new(output)
320    }
321
322    fn hash_len(&self) -> usize {
323        self.alg.len()
324    }
325}
326
327struct Len(usize);
328
329impl KeyType for Len {
330    fn len(&self) -> usize {
331        self.0
332    }
333}
rustls/crypto/ring/tls13.rs

rustls/crypto/ring/
tls13.rs
