rustls/crypto/aws_lc_rs/
tls13.rs

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

rustls/crypto/aws_lc_rs/
tls13.rs
