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

rustls/crypto/aws_lc_rs/
tls13.rs
