rustls/crypto/aws_lc_rs/
tls12.rs

1use alloc::boxed::Box;
2
3use aws_lc_rs::{aead, tls_prf};
4use zeroize::Zeroizing;
5
6use crate::crypto::cipher::{
7    AeadKey, EncodedMessage, InboundOpaque, Iv, KeyBlockShape, MessageDecrypter, MessageEncrypter,
8    NONCE_LEN, Nonce, OutboundOpaque, OutboundPlain, Tls12AeadAlgorithm, UnsupportedOperationError,
9    make_tls12_aad,
10};
11use crate::crypto::enums::{CipherSuite, SignatureScheme};
12use crate::crypto::kx::{ActiveKeyExchange, KeyExchangeAlgorithm, SharedSecret};
13use crate::crypto::tls12::{Prf, PrfSecret};
14use crate::enums::ProtocolVersion;
15use crate::error::Error;
16use crate::msgs::fragmenter::MAX_FRAGMENT_LEN;
17use crate::suites::{CipherSuiteCommon, ConnectionTrafficSecrets};
18use crate::tls12::Tls12CipherSuite;
19use crate::version::TLS12_VERSION;
20
21/// The TLS1.2 ciphersuite TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256.
22pub static TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256: &Tls12CipherSuite = &Tls12CipherSuite {
23    common: CipherSuiteCommon {
24        suite: CipherSuite::TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256,
25        hash_provider: &super::hash::SHA256,
26        confidentiality_limit: u64::MAX,
27    },
28    protocol_version: TLS12_VERSION,
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: &Tls12CipherSuite = &Tls12CipherSuite {
37    common: CipherSuiteCommon {
38        suite: CipherSuite::TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256,
39        hash_provider: &super::hash::SHA256,
40        confidentiality_limit: u64::MAX,
41    },
42    protocol_version: TLS12_VERSION,
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: &Tls12CipherSuite = &Tls12CipherSuite {
51    common: CipherSuiteCommon {
52        suite: CipherSuite::TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
53        hash_provider: &super::hash::SHA256,
54        confidentiality_limit: 1 << 24,
55    },
56    protocol_version: TLS12_VERSION,
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: &Tls12CipherSuite = &Tls12CipherSuite {
65    common: CipherSuiteCommon {
66        suite: CipherSuite::TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
67        hash_provider: &super::hash::SHA384,
68        confidentiality_limit: 1 << 24,
69    },
70    protocol_version: TLS12_VERSION,
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: &Tls12CipherSuite = &Tls12CipherSuite {
79    common: CipherSuiteCommon {
80        suite: CipherSuite::TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
81        hash_provider: &super::hash::SHA256,
82        confidentiality_limit: 1 << 24,
83    },
84    protocol_version: TLS12_VERSION,
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: &Tls12CipherSuite = &Tls12CipherSuite {
93    common: CipherSuiteCommon {
94        suite: CipherSuite::TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
95        hash_provider: &super::hash::SHA384,
96        confidentiality_limit: 1 << 24,
97    },
98    protocol_version: TLS12_VERSION,
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::new(iv).expect("IV length validated by key_block_shape"),
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::new(enc_iv).expect("IV length validated by key_block_shape"),
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).expect("IV length validated by key_block_shape"),
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: EncodedMessage<InboundOpaque<'a>>,
264        seq: u64,
265    ) -> Result<EncodedMessage<&'a [u8]>, 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: EncodedMessage<OutboundPlain<'_>>,
308        seq: u64,
309    ) -> Result<EncodedMessage<OutboundOpaque>, Error> {
310        let total_len = self.encrypted_payload_len(msg.payload.len());
311        let mut payload = OutboundOpaque::with_capacity(total_len);
312
313        let nonce = aead::Nonce::assume_unique_for_key(Nonce::new(&self.iv, seq).to_array()?);
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(EncodedMessage {
324            typ: msg.typ,
325            version: msg.version,
326            payload,
327        })
328    }
329
330    fn encrypted_payload_len(&self, payload_len: usize) -> usize {
331        payload_len + GCM_EXPLICIT_NONCE_LEN + self.enc_key.algorithm().tag_len()
332    }
333}
334
335/// The RFC7905/RFC7539 ChaCha20Poly1305 construction.
336/// This implementation does the AAD construction required in TLS1.2.
337/// TLS1.3 uses `TLS13MessageEncrypter`.
338struct ChaCha20Poly1305MessageEncrypter {
339    enc_key: aead::LessSafeKey,
340    enc_offset: Iv,
341}
342
343/// The RFC7905/RFC7539 ChaCha20Poly1305 construction.
344/// This implementation does the AAD construction required in TLS1.2.
345/// TLS1.3 uses `TLS13MessageDecrypter`.
346struct ChaCha20Poly1305MessageDecrypter {
347    dec_key: aead::LessSafeKey,
348    dec_offset: Iv,
349}
350
351const CHACHAPOLY1305_OVERHEAD: usize = 16;
352
353impl MessageDecrypter for ChaCha20Poly1305MessageDecrypter {
354    fn decrypt<'a>(
355        &mut self,
356        mut msg: EncodedMessage<InboundOpaque<'a>>,
357        seq: u64,
358    ) -> Result<EncodedMessage<&'a [u8]>, Error> {
359        let payload = &msg.payload;
360
361        if payload.len() < CHACHAPOLY1305_OVERHEAD {
362            return Err(Error::DecryptError);
363        }
364
365        let nonce =
366            aead::Nonce::assume_unique_for_key(Nonce::new(&self.dec_offset, seq).to_array()?);
367        let aad = aead::Aad::from(make_tls12_aad(
368            seq,
369            msg.typ,
370            msg.version,
371            payload.len() - CHACHAPOLY1305_OVERHEAD,
372        ));
373
374        let payload = &mut msg.payload;
375        let plain_len = self
376            .dec_key
377            .open_in_place(nonce, aad, payload)
378            .map_err(|_| Error::DecryptError)?
379            .len();
380
381        if plain_len > MAX_FRAGMENT_LEN {
382            return Err(Error::PeerSentOversizedRecord);
383        }
384
385        payload.truncate(plain_len);
386        Ok(msg.into_plain_message())
387    }
388}
389
390impl MessageEncrypter for ChaCha20Poly1305MessageEncrypter {
391    fn encrypt(
392        &mut self,
393        msg: EncodedMessage<OutboundPlain<'_>>,
394        seq: u64,
395    ) -> Result<EncodedMessage<OutboundOpaque>, Error> {
396        let total_len = self.encrypted_payload_len(msg.payload.len());
397        let mut payload = OutboundOpaque::with_capacity(total_len);
398
399        let nonce =
400            aead::Nonce::assume_unique_for_key(Nonce::new(&self.enc_offset, seq).to_array()?);
401        let aad = aead::Aad::from(make_tls12_aad(seq, msg.typ, msg.version, msg.payload.len()));
402        payload.extend_from_chunks(&msg.payload);
403
404        self.enc_key
405            .seal_in_place_append_tag(nonce, aad, &mut payload)
406            .map_err(|_| Error::EncryptError)?;
407
408        Ok(EncodedMessage {
409            typ: msg.typ,
410            version: msg.version,
411            payload,
412        })
413    }
414
415    fn encrypted_payload_len(&self, payload_len: usize) -> usize {
416        payload_len + self.enc_key.algorithm().tag_len()
417    }
418}
419
420fn gcm_iv(write_iv: &[u8], explicit: &[u8]) -> Iv {
421    debug_assert_eq!(write_iv.len(), 4);
422    debug_assert_eq!(explicit.len(), 8);
423
424    // The GCM nonce is constructed from a 32-bit 'salt' derived
425    // from the master-secret, and a 64-bit explicit part,
426    // with no specified construction.  Thanks for that.
427    //
428    // We use the same construction as TLS1.3/ChaCha20Poly1305:
429    // a starting point extracted from the key block, xored with
430    // the sequence number.
431    let mut iv = [0; NONCE_LEN];
432    iv[..4].copy_from_slice(write_iv);
433    iv[4..].copy_from_slice(explicit);
434
435    Iv::new(&iv).expect("IV length is NONCE_LEN, which is within MAX_LEN")
436}
437
438struct Tls12Prf(&'static tls_prf::Algorithm);
439
440impl Prf for Tls12Prf {
441    fn for_key_exchange(
442        &self,
443        output: &mut [u8; 48],
444        kx: Box<dyn ActiveKeyExchange>,
445        peer_pub_key: &[u8],
446        label: &[u8],
447        seed: &[u8],
448    ) -> Result<(), Error> {
449        Tls12PrfSecret {
450            alg: self.0,
451            secret: Secret::KeyExchange(
452                kx.complete_for_tls_version(peer_pub_key, ProtocolVersion::TLSv1_2)?,
453            ),
454        }
455        .prf(output, label, seed);
456        Ok(())
457    }
458
459    fn new_secret(&self, secret: &[u8; 48]) -> Box<dyn PrfSecret> {
460        Box::new(Tls12PrfSecret {
461            alg: self.0,
462            secret: Secret::Master(Zeroizing::new(*secret)),
463        })
464    }
465
466    fn fips(&self) -> bool {
467        super::fips()
468    }
469}
470
471// nb: we can't put a `tls_prf::Secret` in here because it is
472// consumed by `tls_prf::Secret::derive()`
473struct Tls12PrfSecret {
474    alg: &'static tls_prf::Algorithm,
475    secret: Secret,
476}
477
478impl PrfSecret for Tls12PrfSecret {
479    fn prf(&self, output: &mut [u8], label: &[u8], seed: &[u8]) {
480        // safety:
481        // - [1] is safe because our caller guarantees `secret` is non-empty; this is
482        //   the only documented error case.
483        // - [2] is safe in practice because the only failure from `derive()` is due
484        //   to zero `output.len()`; this is outlawed at higher levels
485        let derived = tls_prf::Secret::new(self.alg, self.secret.as_ref())
486            .unwrap() // [1]
487            .derive(label, seed, output.len())
488            .unwrap(); // [2]
489        output.copy_from_slice(derived.as_ref());
490    }
491}
492
493enum Secret {
494    Master(Zeroizing<[u8; 48]>),
495    KeyExchange(SharedSecret),
496}
497
498impl AsRef<[u8]> for Secret {
499    fn as_ref(&self) -> &[u8] {
500        match self {
501            Self::Master(ms) => ms.as_ref(),
502            Self::KeyExchange(kx) => kx.secret_bytes(),
503        }
504    }
505}
rustls/crypto/aws_lc_rs/tls12.rs

rustls/crypto/aws_lc_rs/
tls12.rs
