rustls/crypto/aws_lc_rs/
tls12.rs

1use alloc::boxed::Box;
2
3use aws_lc_rs::{aead, tls_prf};
4
5use crate::crypto::cipher::{
6    AeadKey, InboundOpaqueMessage, Iv, KeyBlockShape, MessageDecrypter, MessageEncrypter,
7    NONCE_LEN, Nonce, Tls12AeadAlgorithm, UnsupportedOperationError, make_tls12_aad,
8};
9use crate::crypto::tls12::Prf;
10use crate::crypto::{ActiveKeyExchange, KeyExchangeAlgorithm};
11use crate::enums::{CipherSuite, SignatureScheme};
12use crate::error::Error;
13use crate::msgs::fragmenter::MAX_FRAGMENT_LEN;
14use crate::msgs::message::{
15    InboundPlainMessage, OutboundOpaqueMessage, OutboundPlainMessage, PrefixedPayload,
16};
17use crate::suites::{CipherSuiteCommon, ConnectionTrafficSecrets, SupportedCipherSuite};
18use crate::tls12::Tls12CipherSuite;
19use crate::version::TLS12;
20
21/// The TLS1.2 ciphersuite TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256.
22pub static TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256: SupportedCipherSuite =
23    SupportedCipherSuite::Tls12(&Tls12CipherSuite {
24        common: CipherSuiteCommon {
25            suite: CipherSuite::TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256,
26            hash_provider: &super::hash::SHA256,
27            confidentiality_limit: u64::MAX,
28        },
29        kx: KeyExchangeAlgorithm::ECDHE,
30        sign: TLS12_ECDSA_SCHEMES,
31        aead_alg: &ChaCha20Poly1305,
32        prf_provider: &Tls12Prf(&tls_prf::P_SHA256),
33    });
34
35/// The TLS1.2 ciphersuite TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
36pub static TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256: SupportedCipherSuite =
37    SupportedCipherSuite::Tls12(&Tls12CipherSuite {
38        common: CipherSuiteCommon {
39            suite: CipherSuite::TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256,
40            hash_provider: &super::hash::SHA256,
41            confidentiality_limit: u64::MAX,
42        },
43        kx: KeyExchangeAlgorithm::ECDHE,
44        sign: TLS12_RSA_SCHEMES,
45        aead_alg: &ChaCha20Poly1305,
46        prf_provider: &Tls12Prf(&tls_prf::P_SHA256),
47    });
48
49/// The TLS1.2 ciphersuite TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
50pub static TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256: SupportedCipherSuite =
51    SupportedCipherSuite::Tls12(&Tls12CipherSuite {
52        common: CipherSuiteCommon {
53            suite: CipherSuite::TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
54            hash_provider: &super::hash::SHA256,
55            confidentiality_limit: 1 << 24,
56        },
57        kx: KeyExchangeAlgorithm::ECDHE,
58        sign: TLS12_RSA_SCHEMES,
59        aead_alg: &AES128_GCM,
60        prf_provider: &Tls12Prf(&tls_prf::P_SHA256),
61    });
62
63/// The TLS1.2 ciphersuite TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
64pub static TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384: SupportedCipherSuite =
65    SupportedCipherSuite::Tls12(&Tls12CipherSuite {
66        common: CipherSuiteCommon {
67            suite: CipherSuite::TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
68            hash_provider: &super::hash::SHA384,
69            confidentiality_limit: 1 << 24,
70        },
71        kx: KeyExchangeAlgorithm::ECDHE,
72        sign: TLS12_RSA_SCHEMES,
73        aead_alg: &AES256_GCM,
74        prf_provider: &Tls12Prf(&tls_prf::P_SHA384),
75    });
76
77/// The TLS1.2 ciphersuite TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
78pub static TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256: SupportedCipherSuite =
79    SupportedCipherSuite::Tls12(&Tls12CipherSuite {
80        common: CipherSuiteCommon {
81            suite: CipherSuite::TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
82            hash_provider: &super::hash::SHA256,
83            confidentiality_limit: 1 << 24,
84        },
85        kx: KeyExchangeAlgorithm::ECDHE,
86        sign: TLS12_ECDSA_SCHEMES,
87        aead_alg: &AES128_GCM,
88        prf_provider: &Tls12Prf(&tls_prf::P_SHA256),
89    });
90
91/// The TLS1.2 ciphersuite TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
92pub static TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384: SupportedCipherSuite =
93    SupportedCipherSuite::Tls12(&Tls12CipherSuite {
94        common: CipherSuiteCommon {
95            suite: CipherSuite::TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
96            hash_provider: &super::hash::SHA384,
97            confidentiality_limit: 1 << 24,
98        },
99        kx: KeyExchangeAlgorithm::ECDHE,
100        sign: TLS12_ECDSA_SCHEMES,
101        aead_alg: &AES256_GCM,
102        prf_provider: &Tls12Prf(&tls_prf::P_SHA384),
103    });
104
105static TLS12_ECDSA_SCHEMES: &[SignatureScheme] = &[
106    SignatureScheme::ED25519,
107    SignatureScheme::ECDSA_NISTP521_SHA512,
108    SignatureScheme::ECDSA_NISTP384_SHA384,
109    SignatureScheme::ECDSA_NISTP256_SHA256,
110];
111
112static TLS12_RSA_SCHEMES: &[SignatureScheme] = &[
113    SignatureScheme::RSA_PSS_SHA512,
114    SignatureScheme::RSA_PSS_SHA384,
115    SignatureScheme::RSA_PSS_SHA256,
116    SignatureScheme::RSA_PKCS1_SHA512,
117    SignatureScheme::RSA_PKCS1_SHA384,
118    SignatureScheme::RSA_PKCS1_SHA256,
119];
120
121pub(crate) static AES128_GCM: GcmAlgorithm = GcmAlgorithm(&aead::AES_128_GCM);
122pub(crate) static AES256_GCM: GcmAlgorithm = GcmAlgorithm(&aead::AES_256_GCM);
123
124pub(crate) struct GcmAlgorithm(&'static aead::Algorithm);
125
126impl Tls12AeadAlgorithm for GcmAlgorithm {
127    fn decrypter(&self, dec_key: AeadKey, dec_iv: &[u8]) -> Box<dyn MessageDecrypter> {
128        // safety: see `encrypter()`.
129        let dec_key =
130            aead::TlsRecordOpeningKey::new(self.0, aead::TlsProtocolId::TLS12, dec_key.as_ref())
131                .unwrap();
132
133        let mut ret = GcmMessageDecrypter {
134            dec_key,
135            dec_salt: [0u8; 4],
136        };
137
138        debug_assert_eq!(dec_iv.len(), 4);
139        ret.dec_salt.copy_from_slice(dec_iv);
140        Box::new(ret)
141    }
142
143    fn encrypter(
144        &self,
145        enc_key: AeadKey,
146        write_iv: &[u8],
147        explicit: &[u8],
148    ) -> Box<dyn MessageEncrypter> {
149        // safety: `TlsRecordSealingKey::new` fails if
150        // - `enc_key`'s length is wrong for `algorithm`.  But the length is defined by
151        //   `algorithm.key_len()` in `key_block_shape()`, below.
152        // - `algorithm` is not supported: but `AES_128_GCM` and `AES_256_GCM` is.
153        // thus, this `unwrap()` is unreachable.
154        //
155        // `TlsProtocolId::TLS13` is deliberate: we reuse the nonce construction from
156        // RFC7905 and TLS13: a random starting point, XOR'd with the sequence number.  This means
157        // `TlsProtocolId::TLS12` (which wants to see a plain sequence number) is unsuitable.
158        //
159        // The most important property is that nonce is unique per key, which is satisfied by
160        // this construction, even if the nonce is not monotonically increasing.
161        let enc_key =
162            aead::TlsRecordSealingKey::new(self.0, aead::TlsProtocolId::TLS13, enc_key.as_ref())
163                .unwrap();
164        let iv = gcm_iv(write_iv, explicit);
165        Box::new(GcmMessageEncrypter { enc_key, iv })
166    }
167
168    fn key_block_shape(&self) -> KeyBlockShape {
169        KeyBlockShape {
170            enc_key_len: self.0.key_len(),
171            fixed_iv_len: 4,
172            explicit_nonce_len: 8,
173        }
174    }
175
176    fn extract_keys(
177        &self,
178        key: AeadKey,
179        write_iv: &[u8],
180        explicit: &[u8],
181    ) -> Result<ConnectionTrafficSecrets, UnsupportedOperationError> {
182        let iv = gcm_iv(write_iv, explicit);
183        Ok(match self.0.key_len() {
184            16 => ConnectionTrafficSecrets::Aes128Gcm { key, iv },
185            32 => ConnectionTrafficSecrets::Aes256Gcm { key, iv },
186            _ => unreachable!(),
187        })
188    }
189
190    fn fips(&self) -> bool {
191        super::fips()
192    }
193}
194
195pub(crate) struct ChaCha20Poly1305;
196
197impl Tls12AeadAlgorithm for ChaCha20Poly1305 {
198    fn decrypter(&self, dec_key: AeadKey, iv: &[u8]) -> Box<dyn MessageDecrypter> {
199        let dec_key = aead::LessSafeKey::new(
200            aead::UnboundKey::new(&aead::CHACHA20_POLY1305, dec_key.as_ref()).unwrap(),
201        );
202        Box::new(ChaCha20Poly1305MessageDecrypter {
203            dec_key,
204            dec_offset: Iv::copy(iv),
205        })
206    }
207
208    fn encrypter(&self, enc_key: AeadKey, enc_iv: &[u8], _: &[u8]) -> Box<dyn MessageEncrypter> {
209        let enc_key = aead::LessSafeKey::new(
210            aead::UnboundKey::new(&aead::CHACHA20_POLY1305, enc_key.as_ref()).unwrap(),
211        );
212        Box::new(ChaCha20Poly1305MessageEncrypter {
213            enc_key,
214            enc_offset: Iv::copy(enc_iv),
215        })
216    }
217
218    fn key_block_shape(&self) -> KeyBlockShape {
219        KeyBlockShape {
220            enc_key_len: 32,
221            fixed_iv_len: 12,
222            explicit_nonce_len: 0,
223        }
224    }
225
226    fn extract_keys(
227        &self,
228        key: AeadKey,
229        iv: &[u8],
230        _explicit: &[u8],
231    ) -> Result<ConnectionTrafficSecrets, UnsupportedOperationError> {
232        // This should always be true because KeyBlockShape and the Iv nonce len are in agreement.
233        debug_assert_eq!(aead::NONCE_LEN, iv.len());
234        Ok(ConnectionTrafficSecrets::Chacha20Poly1305 {
235            key,
236            iv: Iv::new(iv[..].try_into().unwrap()),
237        })
238    }
239
240    fn fips(&self) -> bool {
241        false // not FIPS approved
242    }
243}
244
245/// A `MessageEncrypter` for AES-GCM AEAD ciphersuites. TLS 1.2 only.
246struct GcmMessageEncrypter {
247    enc_key: aead::TlsRecordSealingKey,
248    iv: Iv,
249}
250
251/// A `MessageDecrypter` for AES-GCM AEAD ciphersuites.  TLS1.2 only.
252struct GcmMessageDecrypter {
253    dec_key: aead::TlsRecordOpeningKey,
254    dec_salt: [u8; 4],
255}
256
257const GCM_EXPLICIT_NONCE_LEN: usize = 8;
258const GCM_OVERHEAD: usize = GCM_EXPLICIT_NONCE_LEN + 16;
259
260impl MessageDecrypter for GcmMessageDecrypter {
261    fn decrypt<'a>(
262        &mut self,
263        mut msg: InboundOpaqueMessage<'a>,
264        seq: u64,
265    ) -> Result<InboundPlainMessage<'a>, Error> {
266        let payload = &msg.payload;
267        if payload.len() < GCM_OVERHEAD {
268            return Err(Error::DecryptError);
269        }
270
271        let nonce = {
272            let mut nonce = [0u8; 12];
273            nonce[..4].copy_from_slice(&self.dec_salt);
274            nonce[4..].copy_from_slice(&payload[..8]);
275            aead::Nonce::assume_unique_for_key(nonce)
276        };
277
278        let aad = aead::Aad::from(make_tls12_aad(
279            seq,
280            msg.typ,
281            msg.version,
282            payload.len() - GCM_OVERHEAD,
283        ));
284
285        let payload = &mut msg.payload;
286        let plain_len = self
287            .dec_key
288            .open_in_place(nonce, aad, &mut payload[GCM_EXPLICIT_NONCE_LEN..])
289            .map_err(|_| Error::DecryptError)?
290            .len();
291
292        if plain_len > MAX_FRAGMENT_LEN {
293            return Err(Error::PeerSentOversizedRecord);
294        }
295
296        Ok(
297            msg.into_plain_message_range(
298                GCM_EXPLICIT_NONCE_LEN..GCM_EXPLICIT_NONCE_LEN + plain_len,
299            ),
300        )
301    }
302}
303
304impl MessageEncrypter for GcmMessageEncrypter {
305    fn encrypt(
306        &mut self,
307        msg: OutboundPlainMessage<'_>,
308        seq: u64,
309    ) -> Result<OutboundOpaqueMessage, Error> {
310        let total_len = self.encrypted_payload_len(msg.payload.len());
311        let mut payload = PrefixedPayload::with_capacity(total_len);
312
313        let nonce = aead::Nonce::assume_unique_for_key(Nonce::new(&self.iv, seq).0);
314        let aad = aead::Aad::from(make_tls12_aad(seq, msg.typ, msg.version, msg.payload.len()));
315        payload.extend_from_slice(&nonce.as_ref()[4..]);
316        payload.extend_from_chunks(&msg.payload);
317
318        self.enc_key
319            .seal_in_place_separate_tag(nonce, aad, &mut payload.as_mut()[GCM_EXPLICIT_NONCE_LEN..])
320            .map(|tag| payload.extend_from_slice(tag.as_ref()))
321            .map_err(|_| Error::EncryptError)?;
322
323        Ok(OutboundOpaqueMessage::new(msg.typ, msg.version, payload))
324    }
325
326    fn encrypted_payload_len(&self, payload_len: usize) -> usize {
327        payload_len + GCM_EXPLICIT_NONCE_LEN + self.enc_key.algorithm().tag_len()
328    }
329}
330
331/// The RFC7905/RFC7539 ChaCha20Poly1305 construction.
332/// This implementation does the AAD construction required in TLS1.2.
333/// TLS1.3 uses `TLS13MessageEncrypter`.
334struct ChaCha20Poly1305MessageEncrypter {
335    enc_key: aead::LessSafeKey,
336    enc_offset: Iv,
337}
338
339/// The RFC7905/RFC7539 ChaCha20Poly1305 construction.
340/// This implementation does the AAD construction required in TLS1.2.
341/// TLS1.3 uses `TLS13MessageDecrypter`.
342struct ChaCha20Poly1305MessageDecrypter {
343    dec_key: aead::LessSafeKey,
344    dec_offset: Iv,
345}
346
347const CHACHAPOLY1305_OVERHEAD: usize = 16;
348
349impl MessageDecrypter for ChaCha20Poly1305MessageDecrypter {
350    fn decrypt<'a>(
351        &mut self,
352        mut msg: InboundOpaqueMessage<'a>,
353        seq: u64,
354    ) -> Result<InboundPlainMessage<'a>, Error> {
355        let payload = &msg.payload;
356
357        if payload.len() < CHACHAPOLY1305_OVERHEAD {
358            return Err(Error::DecryptError);
359        }
360
361        let nonce = aead::Nonce::assume_unique_for_key(Nonce::new(&self.dec_offset, seq).0);
362        let aad = aead::Aad::from(make_tls12_aad(
363            seq,
364            msg.typ,
365            msg.version,
366            payload.len() - CHACHAPOLY1305_OVERHEAD,
367        ));
368
369        let payload = &mut msg.payload;
370        let plain_len = self
371            .dec_key
372            .open_in_place(nonce, aad, payload)
373            .map_err(|_| Error::DecryptError)?
374            .len();
375
376        if plain_len > MAX_FRAGMENT_LEN {
377            return Err(Error::PeerSentOversizedRecord);
378        }
379
380        payload.truncate(plain_len);
381        Ok(msg.into_plain_message())
382    }
383}
384
385impl MessageEncrypter for ChaCha20Poly1305MessageEncrypter {
386    fn encrypt(
387        &mut self,
388        msg: OutboundPlainMessage<'_>,
389        seq: u64,
390    ) -> Result<OutboundOpaqueMessage, Error> {
391        let total_len = self.encrypted_payload_len(msg.payload.len());
392        let mut payload = PrefixedPayload::with_capacity(total_len);
393
394        let nonce = aead::Nonce::assume_unique_for_key(Nonce::new(&self.enc_offset, seq).0);
395        let aad = aead::Aad::from(make_tls12_aad(seq, msg.typ, msg.version, msg.payload.len()));
396        payload.extend_from_chunks(&msg.payload);
397
398        self.enc_key
399            .seal_in_place_append_tag(nonce, aad, &mut payload)
400            .map_err(|_| Error::EncryptError)?;
401
402        Ok(OutboundOpaqueMessage::new(msg.typ, msg.version, payload))
403    }
404
405    fn encrypted_payload_len(&self, payload_len: usize) -> usize {
406        payload_len + self.enc_key.algorithm().tag_len()
407    }
408}
409
410fn gcm_iv(write_iv: &[u8], explicit: &[u8]) -> Iv {
411    debug_assert_eq!(write_iv.len(), 4);
412    debug_assert_eq!(explicit.len(), 8);
413
414    // The GCM nonce is constructed from a 32-bit 'salt' derived
415    // from the master-secret, and a 64-bit explicit part,
416    // with no specified construction.  Thanks for that.
417    //
418    // We use the same construction as TLS1.3/ChaCha20Poly1305:
419    // a starting point extracted from the key block, xored with
420    // the sequence number.
421    let mut iv = [0; NONCE_LEN];
422    iv[..4].copy_from_slice(write_iv);
423    iv[4..].copy_from_slice(explicit);
424
425    Iv::new(iv)
426}
427
428struct Tls12Prf(&'static tls_prf::Algorithm);
429
430impl Prf for Tls12Prf {
431    fn for_secret(&self, output: &mut [u8], secret: &[u8], label: &[u8], seed: &[u8]) {
432        // safety:
433        // - [1] is safe because our caller guarantees `secret` is non-empty; this is
434        //   the only documented error case.
435        // - [2] is safe in practice because the only failure from `derive()` is due
436        //   to zero `output.len()`; this is outlawed at higher levels
437        let derived = tls_prf::Secret::new(self.0, secret)
438            .unwrap() // [1]
439            .derive(label, seed, output.len())
440            .unwrap(); // [2]
441        output.copy_from_slice(derived.as_ref());
442    }
443
444    fn for_key_exchange(
445        &self,
446        output: &mut [u8; 48],
447        kx: Box<dyn ActiveKeyExchange>,
448        peer_pub_key: &[u8],
449        label: &[u8],
450        seed: &[u8],
451    ) -> Result<(), Error> {
452        self.for_secret(
453            output,
454            kx.complete_for_tls_version(peer_pub_key, &TLS12)?
455                .secret_bytes(),
456            label,
457            seed,
458        );
459        Ok(())
460    }
461
462    fn fips(&self) -> bool {
463        super::fips()
464    }
465}
rustls/crypto/aws_lc_rs/tls12.rs

rustls/crypto/aws_lc_rs/
tls12.rs
