rustls/crypto/ring/
tls12.rs

1use crate::crypto::cipher::{
2    make_tls12_aad, AeadKey, Iv, KeyBlockShape, MessageDecrypter, MessageEncrypter, Nonce,
3    Tls12AeadAlgorithm, UnsupportedOperationError, NONCE_LEN,
4};
5use crate::crypto::tls12::PrfUsingHmac;
6use crate::crypto::KeyExchangeAlgorithm;
7use crate::enums::{CipherSuite, SignatureScheme};
8use crate::error::Error;
9use crate::msgs::fragmenter::MAX_FRAGMENT_LEN;
10use crate::msgs::message::{BorrowedPlainMessage, OpaqueMessage, PlainMessage};
11use crate::suites::{CipherSuiteCommon, ConnectionTrafficSecrets, SupportedCipherSuite};
12use crate::tls12::Tls12CipherSuite;
13
14use alloc::boxed::Box;
15use alloc::vec::Vec;
16
17use super::ring_like::aead;
18
19/// The TLS1.2 ciphersuite TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256.
20pub static TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256: SupportedCipherSuite =
21    SupportedCipherSuite::Tls12(&Tls12CipherSuite {
22        common: CipherSuiteCommon {
23            suite: CipherSuite::TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256,
24            hash_provider: &super::hash::SHA256,
25            confidentiality_limit: u64::MAX,
26            integrity_limit: 1 << 36,
27        },
28        kx: KeyExchangeAlgorithm::ECDHE,
29        sign: TLS12_ECDSA_SCHEMES,
30        aead_alg: &ChaCha20Poly1305,
31        prf_provider: &PrfUsingHmac(&super::hmac::HMAC_SHA256),
32    });
33
34/// The TLS1.2 ciphersuite TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
35pub static TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256: SupportedCipherSuite =
36    SupportedCipherSuite::Tls12(&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            integrity_limit: 1 << 36,
42        },
43        kx: KeyExchangeAlgorithm::ECDHE,
44        sign: TLS12_RSA_SCHEMES,
45        aead_alg: &ChaCha20Poly1305,
46        prf_provider: &PrfUsingHmac(&super::hmac::HMAC_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 << 23,
56            integrity_limit: 1 << 52,
57        },
58        kx: KeyExchangeAlgorithm::ECDHE,
59        sign: TLS12_RSA_SCHEMES,
60        aead_alg: &AES128_GCM,
61        prf_provider: &PrfUsingHmac(&super::hmac::HMAC_SHA256),
62    });
63
64/// The TLS1.2 ciphersuite TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
65pub static TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384: SupportedCipherSuite =
66    SupportedCipherSuite::Tls12(&Tls12CipherSuite {
67        common: CipherSuiteCommon {
68            suite: CipherSuite::TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
69            hash_provider: &super::hash::SHA384,
70            confidentiality_limit: 1 << 23,
71            integrity_limit: 1 << 52,
72        },
73        kx: KeyExchangeAlgorithm::ECDHE,
74        sign: TLS12_RSA_SCHEMES,
75        aead_alg: &AES256_GCM,
76        prf_provider: &PrfUsingHmac(&super::hmac::HMAC_SHA384),
77    });
78
79/// The TLS1.2 ciphersuite TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
80pub static TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256: SupportedCipherSuite =
81    SupportedCipherSuite::Tls12(&Tls12CipherSuite {
82        common: CipherSuiteCommon {
83            suite: CipherSuite::TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
84            hash_provider: &super::hash::SHA256,
85            confidentiality_limit: 1 << 23,
86            integrity_limit: 1 << 52,
87        },
88        kx: KeyExchangeAlgorithm::ECDHE,
89        sign: TLS12_ECDSA_SCHEMES,
90        aead_alg: &AES128_GCM,
91        prf_provider: &PrfUsingHmac(&super::hmac::HMAC_SHA256),
92    });
93
94/// The TLS1.2 ciphersuite TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
95pub static TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384: SupportedCipherSuite =
96    SupportedCipherSuite::Tls12(&Tls12CipherSuite {
97        common: CipherSuiteCommon {
98            suite: CipherSuite::TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
99            hash_provider: &super::hash::SHA384,
100            confidentiality_limit: 1 << 23,
101            integrity_limit: 1 << 52,
102        },
103        kx: KeyExchangeAlgorithm::ECDHE,
104        sign: TLS12_ECDSA_SCHEMES,
105        aead_alg: &AES256_GCM,
106        prf_provider: &PrfUsingHmac(&super::hmac::HMAC_SHA384),
107    });
108
109static TLS12_ECDSA_SCHEMES: &[SignatureScheme] = &[
110    SignatureScheme::ED25519,
111    SignatureScheme::ECDSA_NISTP521_SHA512,
112    SignatureScheme::ECDSA_NISTP384_SHA384,
113    SignatureScheme::ECDSA_NISTP256_SHA256,
114];
115
116static TLS12_RSA_SCHEMES: &[SignatureScheme] = &[
117    SignatureScheme::RSA_PSS_SHA512,
118    SignatureScheme::RSA_PSS_SHA384,
119    SignatureScheme::RSA_PSS_SHA256,
120    SignatureScheme::RSA_PKCS1_SHA512,
121    SignatureScheme::RSA_PKCS1_SHA384,
122    SignatureScheme::RSA_PKCS1_SHA256,
123];
124
125pub(crate) static AES128_GCM: GcmAlgorithm = GcmAlgorithm(&aead::AES_128_GCM);
126pub(crate) static AES256_GCM: GcmAlgorithm = GcmAlgorithm(&aead::AES_256_GCM);
127
128pub(crate) struct GcmAlgorithm(&'static aead::Algorithm);
129
130impl Tls12AeadAlgorithm for GcmAlgorithm {
131    fn decrypter(&self, dec_key: AeadKey, dec_iv: &[u8]) -> Box<dyn MessageDecrypter> {
132        let dec_key =
133            aead::LessSafeKey::new(aead::UnboundKey::new(self.0, dec_key.as_ref()).unwrap());
134
135        let mut ret = GcmMessageDecrypter {
136            dec_key,
137            dec_salt: [0u8; 4],
138        };
139
140        debug_assert_eq!(dec_iv.len(), 4);
141        ret.dec_salt.copy_from_slice(dec_iv);
142        Box::new(ret)
143    }
144
145    fn encrypter(
146        &self,
147        enc_key: AeadKey,
148        write_iv: &[u8],
149        explicit: &[u8],
150    ) -> Box<dyn MessageEncrypter> {
151        let enc_key =
152            aead::LessSafeKey::new(aead::UnboundKey::new(self.0, enc_key.as_ref()).unwrap());
153        let iv = gcm_iv(write_iv, explicit);
154        Box::new(GcmMessageEncrypter { enc_key, iv })
155    }
156
157    fn key_block_shape(&self) -> KeyBlockShape {
158        KeyBlockShape {
159            enc_key_len: self.0.key_len(),
160            fixed_iv_len: 4,
161            explicit_nonce_len: 8,
162        }
163    }
164
165    fn extract_keys(
166        &self,
167        key: AeadKey,
168        write_iv: &[u8],
169        explicit: &[u8],
170    ) -> Result<ConnectionTrafficSecrets, UnsupportedOperationError> {
171        let iv = gcm_iv(write_iv, explicit);
172        Ok(match self.0.key_len() {
173            16 => ConnectionTrafficSecrets::Aes128Gcm { key, iv },
174            32 => ConnectionTrafficSecrets::Aes256Gcm { key, iv },
175            _ => unreachable!(),
176        })
177    }
178}
179
180pub(crate) struct ChaCha20Poly1305;
181
182impl Tls12AeadAlgorithm for ChaCha20Poly1305 {
183    fn decrypter(&self, dec_key: AeadKey, iv: &[u8]) -> Box<dyn MessageDecrypter> {
184        let dec_key = aead::LessSafeKey::new(
185            aead::UnboundKey::new(&aead::CHACHA20_POLY1305, dec_key.as_ref()).unwrap(),
186        );
187        Box::new(ChaCha20Poly1305MessageDecrypter {
188            dec_key,
189            dec_offset: Iv::copy(iv),
190        })
191    }
192
193    fn encrypter(&self, enc_key: AeadKey, enc_iv: &[u8], _: &[u8]) -> Box<dyn MessageEncrypter> {
194        let enc_key = aead::LessSafeKey::new(
195            aead::UnboundKey::new(&aead::CHACHA20_POLY1305, enc_key.as_ref()).unwrap(),
196        );
197        Box::new(ChaCha20Poly1305MessageEncrypter {
198            enc_key,
199            enc_offset: Iv::copy(enc_iv),
200        })
201    }
202
203    fn key_block_shape(&self) -> KeyBlockShape {
204        KeyBlockShape {
205            enc_key_len: 32,
206            fixed_iv_len: 12,
207            explicit_nonce_len: 0,
208        }
209    }
210
211    fn extract_keys(
212        &self,
213        key: AeadKey,
214        iv: &[u8],
215        _explicit: &[u8],
216    ) -> Result<ConnectionTrafficSecrets, UnsupportedOperationError> {
217        // This should always be true because KeyBlockShape and the Iv nonce len are in agreement.
218        debug_assert_eq!(aead::NONCE_LEN, iv.len());
219        Ok(ConnectionTrafficSecrets::Chacha20Poly1305 {
220            key,
221            iv: Iv::new(iv[..].try_into().unwrap()),
222        })
223    }
224}
225
226/// A `MessageEncrypter` for AES-GCM AEAD ciphersuites. TLS 1.2 only.
227struct GcmMessageEncrypter {
228    enc_key: aead::LessSafeKey,
229    iv: Iv,
230}
231
232/// A `MessageDecrypter` for AES-GCM AEAD ciphersuites.  TLS1.2 only.
233struct GcmMessageDecrypter {
234    dec_key: aead::LessSafeKey,
235    dec_salt: [u8; 4],
236}
237
238const GCM_EXPLICIT_NONCE_LEN: usize = 8;
239const GCM_OVERHEAD: usize = GCM_EXPLICIT_NONCE_LEN + 16;
240
241impl MessageDecrypter for GcmMessageDecrypter {
242    fn decrypt(&mut self, mut msg: OpaqueMessage, seq: u64) -> Result<PlainMessage, Error> {
243        let payload = msg.payload();
244        if payload.len() < GCM_OVERHEAD {
245            return Err(Error::DecryptError);
246        }
247
248        let nonce = {
249            let mut nonce = [0u8; 12];
250            nonce[..4].copy_from_slice(&self.dec_salt);
251            nonce[4..].copy_from_slice(&payload[..8]);
252            aead::Nonce::assume_unique_for_key(nonce)
253        };
254
255        let aad = aead::Aad::from(make_tls12_aad(
256            seq,
257            msg.typ,
258            msg.version,
259            payload.len() - GCM_OVERHEAD,
260        ));
261
262        let payload = msg.payload_mut();
263        let plain_len = self
264            .dec_key
265            .open_within(nonce, aad, payload, GCM_EXPLICIT_NONCE_LEN..)
266            .map_err(|_| Error::DecryptError)?
267            .len();
268
269        if plain_len > MAX_FRAGMENT_LEN {
270            return Err(Error::PeerSentOversizedRecord);
271        }
272
273        payload.truncate(plain_len);
274        Ok(msg.into_plain_message())
275    }
276}
277
278impl MessageEncrypter for GcmMessageEncrypter {
279    fn encrypt(&mut self, msg: BorrowedPlainMessage, seq: u64) -> Result<OpaqueMessage, Error> {
280        let nonce = aead::Nonce::assume_unique_for_key(Nonce::new(&self.iv, seq).0);
281        let aad = aead::Aad::from(make_tls12_aad(seq, msg.typ, msg.version, msg.payload.len()));
282
283        let total_len = self.encrypted_payload_len(msg.payload.len());
284        let mut payload = Vec::with_capacity(total_len);
285        payload.extend_from_slice(&nonce.as_ref()[4..]);
286        payload.extend_from_slice(msg.payload);
287
288        self.enc_key
289            .seal_in_place_separate_tag(nonce, aad, &mut payload[GCM_EXPLICIT_NONCE_LEN..])
290            .map(|tag| payload.extend(tag.as_ref()))
291            .map_err(|_| Error::EncryptError)?;
292
293        Ok(OpaqueMessage::new(msg.typ, msg.version, payload))
294    }
295
296    fn encrypted_payload_len(&self, payload_len: usize) -> usize {
297        payload_len + GCM_EXPLICIT_NONCE_LEN + self.enc_key.algorithm().tag_len()
298    }
299}
300
301/// The RFC7905/RFC7539 ChaCha20Poly1305 construction.
302/// This implementation does the AAD construction required in TLS1.2.
303/// TLS1.3 uses `TLS13MessageEncrypter`.
304struct ChaCha20Poly1305MessageEncrypter {
305    enc_key: aead::LessSafeKey,
306    enc_offset: Iv,
307}
308
309/// The RFC7905/RFC7539 ChaCha20Poly1305 construction.
310/// This implementation does the AAD construction required in TLS1.2.
311/// TLS1.3 uses `TLS13MessageDecrypter`.
312struct ChaCha20Poly1305MessageDecrypter {
313    dec_key: aead::LessSafeKey,
314    dec_offset: Iv,
315}
316
317const CHACHAPOLY1305_OVERHEAD: usize = 16;
318
319impl MessageDecrypter for ChaCha20Poly1305MessageDecrypter {
320    fn decrypt(&mut self, mut msg: OpaqueMessage, seq: u64) -> Result<PlainMessage, Error> {
321        let payload = msg.payload();
322
323        if payload.len() < CHACHAPOLY1305_OVERHEAD {
324            return Err(Error::DecryptError);
325        }
326
327        let nonce = aead::Nonce::assume_unique_for_key(Nonce::new(&self.dec_offset, seq).0);
328        let aad = aead::Aad::from(make_tls12_aad(
329            seq,
330            msg.typ,
331            msg.version,
332            payload.len() - CHACHAPOLY1305_OVERHEAD,
333        ));
334
335        let payload = msg.payload_mut();
336        let plain_len = self
337            .dec_key
338            .open_in_place(nonce, aad, payload)
339            .map_err(|_| Error::DecryptError)?
340            .len();
341
342        if plain_len > MAX_FRAGMENT_LEN {
343            return Err(Error::PeerSentOversizedRecord);
344        }
345
346        payload.truncate(plain_len);
347        Ok(msg.into_plain_message())
348    }
349}
350
351impl MessageEncrypter for ChaCha20Poly1305MessageEncrypter {
352    fn encrypt(&mut self, msg: BorrowedPlainMessage, seq: u64) -> Result<OpaqueMessage, Error> {
353        let nonce = aead::Nonce::assume_unique_for_key(Nonce::new(&self.enc_offset, seq).0);
354        let aad = aead::Aad::from(make_tls12_aad(seq, msg.typ, msg.version, msg.payload.len()));
355
356        let total_len = self.encrypted_payload_len(msg.payload.len());
357        let mut buf = Vec::with_capacity(total_len);
358        buf.extend_from_slice(msg.payload);
359
360        self.enc_key
361            .seal_in_place_append_tag(nonce, aad, &mut buf)
362            .map_err(|_| Error::EncryptError)?;
363
364        Ok(OpaqueMessage::new(msg.typ, msg.version, buf))
365    }
366
367    fn encrypted_payload_len(&self, payload_len: usize) -> usize {
368        payload_len + self.enc_key.algorithm().tag_len()
369    }
370}
371
372fn gcm_iv(write_iv: &[u8], explicit: &[u8]) -> Iv {
373    debug_assert_eq!(write_iv.len(), 4);
374    debug_assert_eq!(explicit.len(), 8);
375
376    // The GCM nonce is constructed from a 32-bit 'salt' derived
377    // from the master-secret, and a 64-bit explicit part,
378    // with no specified construction.  Thanks for that.
379    //
380    // We use the same construction as TLS1.3/ChaCha20Poly1305:
381    // a starting point extracted from the key block, xored with
382    // the sequence number.
383    let mut iv = [0; NONCE_LEN];
384    iv[..4].copy_from_slice(write_iv);
385    iv[4..].copy_from_slice(explicit);
386
387    Iv::new(iv)
388}
rustls/crypto/ring/tls12.rs

rustls/crypto/ring/
tls12.rs
