tlspuffin/tls/rustls/
suites.rs

1use crate::tls::rustls::msgs::enums::{
2    CipherSuite, ProtocolVersion, SignatureAlgorithm, SignatureScheme,
3};
4use crate::tls::rustls::msgs::handshake::DecomposedSignatureScheme;
5use crate::tls::rustls::tls12::{
6    Tls12CipherSuite, TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
7    TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256,
8    TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
9    TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256,
10};
11use crate::tls::rustls::tls13::{
12    Tls13CipherSuite, TLS13_AES_128_GCM_SHA256, TLS13_AES_256_GCM_SHA384,
13    TLS13_CHACHA20_POLY1305_SHA256,
14};
15use crate::tls::rustls::versions::{SupportedProtocolVersion, TLS12, TLS13};
16
17/// Bulk symmetric encryption scheme used by a cipher suite.
18#[allow(non_camel_case_types)]
19#[derive(Debug, PartialEq)]
20pub enum BulkAlgorithm {
21    /// AES with 128-bit keys in Galois counter mode.
22    Aes128Gcm,
23
24    /// AES with 256-bit keys in Galois counter mode.
25    Aes256Gcm,
26
27    /// Chacha20 for confidentiality with poly1305 for authenticity.
28    Chacha20Poly1305,
29}
30
31/// Common state for cipher suites (both for TLS 1.2 and TLS 1.3)
32pub struct CipherSuiteCommon {
33    /// The TLS enumeration naming this cipher suite.
34    pub suite: CipherSuite,
35
36    /// How to do bulk encryption.
37    pub bulk: BulkAlgorithm,
38
39    pub aead_algorithm: &'static ring::aead::Algorithm,
40}
41
42/// A cipher suite supported by rustls.
43///
44/// All possible instances of this type are provided by the library in
45/// the [`ALL_CIPHER_SUITES`] array.
46#[derive(Clone, Copy, Debug, PartialEq)]
47pub enum SupportedCipherSuite {
48    /// A TLS 1.2 cipher suite
49    Tls12(&'static Tls12CipherSuite),
50    /// A TLS 1.3 cipher suite
51    Tls13(&'static Tls13CipherSuite),
52}
53
54impl SupportedCipherSuite {
55    /// Which hash function to use with this suite.
56    pub fn hash_algorithm(&self) -> &'static ring::digest::Algorithm {
57        match self {
58            SupportedCipherSuite::Tls12(inner) => inner.hash_algorithm(),
59            SupportedCipherSuite::Tls13(inner) => inner.hash_algorithm(),
60        }
61    }
62
63    /// The cipher suite's identifier
64    pub fn suite(&self) -> CipherSuite {
65        self.common().suite
66    }
67
68    pub fn common(&self) -> &CipherSuiteCommon {
69        match self {
70            SupportedCipherSuite::Tls12(inner) => &inner.common,
71            SupportedCipherSuite::Tls13(inner) => &inner.common,
72        }
73    }
74
75    pub fn tls13(&self) -> Option<&'static Tls13CipherSuite> {
76        match self {
77            SupportedCipherSuite::Tls12(_) => None,
78            SupportedCipherSuite::Tls13(inner) => Some(inner),
79        }
80    }
81
82    pub fn tls12(&self) -> Option<&'static Tls12CipherSuite> {
83        match self {
84            SupportedCipherSuite::Tls12(inner) => Some(inner),
85            SupportedCipherSuite::Tls13(_inner) => None,
86        }
87    }
88
89    /// Return supported protocol version for the cipher suite.
90    pub fn version(&self) -> &'static SupportedProtocolVersion {
91        match self {
92            SupportedCipherSuite::Tls12(_) => &TLS12,
93            SupportedCipherSuite::Tls13(_) => &TLS13,
94        }
95    }
96
97    /// Return true if this suite is usable for a key only offering `sig_alg`
98    /// signatures.  This resolves to true for all TLS1.3 suites.
99    pub fn usable_for_signature_algorithm(&self, _sig_alg: SignatureAlgorithm) -> bool {
100        match self {
101            SupportedCipherSuite::Tls13(_) => true, /* no constraint expressed by ciphersuite */
102            // (e.g., TLS1.3)
103            SupportedCipherSuite::Tls12(inner) => {
104                inner.sign.iter().any(|scheme| scheme.sign() == _sig_alg)
105            }
106        }
107    }
108}
109
110/// A list of all the cipher suites supported by rustls.
111pub static ALL_CIPHER_SUITES: &[SupportedCipherSuite] = &[
112    // TLS1.3 suites
113    TLS13_AES_256_GCM_SHA384,
114    TLS13_AES_128_GCM_SHA256,
115    TLS13_CHACHA20_POLY1305_SHA256,
116    // TLS1.2 suites
117    TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
118    TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
119    TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256,
120    TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
121    TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
122    TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256,
123];
124
125/// The cipher suite configuration that an application should use by default.
126///
127/// This will be [`ALL_CIPHER_SUITES`] sans any supported cipher suites that
128/// shouldn't be enabled by most applications.
129pub static DEFAULT_CIPHER_SUITES: &[SupportedCipherSuite] = ALL_CIPHER_SUITES;
130
131// These both O(N^2)!
132pub fn choose_ciphersuite_preferring_client(
133    client_suites: &[CipherSuite],
134    server_suites: &[SupportedCipherSuite],
135) -> Option<SupportedCipherSuite> {
136    for client_suite in client_suites {
137        if let Some(selected) = server_suites.iter().find(|x| *client_suite == x.suite()) {
138            return Some(*selected);
139        }
140    }
141
142    None
143}
144
145pub fn choose_ciphersuite_preferring_server(
146    client_suites: &[CipherSuite],
147    server_suites: &[SupportedCipherSuite],
148) -> Option<SupportedCipherSuite> {
149    if let Some(selected) = server_suites
150        .iter()
151        .find(|x| client_suites.contains(&x.suite()))
152    {
153        return Some(*selected);
154    }
155
156    None
157}
158
159/// Return a list of the ciphersuites in `all` with the suites
160/// incompatible with `SignatureAlgorithm` `sigalg` removed.
161pub fn reduce_given_sigalg(
162    all: &[SupportedCipherSuite],
163    sigalg: SignatureAlgorithm,
164) -> Vec<SupportedCipherSuite> {
165    all.iter()
166        .filter(|&&suite| suite.usable_for_signature_algorithm(sigalg))
167        .copied()
168        .collect()
169}
170
171/// Return a list of the ciphersuites in `all` with the suites
172/// incompatible with the chosen `version` removed.
173pub fn reduce_given_version(
174    all: &[SupportedCipherSuite],
175    version: ProtocolVersion,
176) -> Vec<SupportedCipherSuite> {
177    all.iter()
178        .filter(|&&suite| suite.version().version == version)
179        .copied()
180        .collect()
181}
182
183/// Return true if `sigscheme` is usable by any of the given suites.
184pub fn compatible_sigscheme_for_suites(
185    sigscheme: SignatureScheme,
186    common_suites: &[SupportedCipherSuite],
187) -> bool {
188    let sigalg = sigscheme.sign();
189    common_suites
190        .iter()
191        .any(|&suite| suite.usable_for_signature_algorithm(sigalg))
192}
193
194#[cfg(test)]
195mod tests {
196    use super::*;
197    use crate::tls::rustls::msgs::enums::CipherSuite;
198
199    #[test_log::test]
200    fn test_client_pref() {
201        let client = vec![
202            CipherSuite::TLS13_AES_128_GCM_SHA256,
203            CipherSuite::TLS13_AES_256_GCM_SHA384,
204        ];
205        let server = vec![TLS13_AES_256_GCM_SHA384, TLS13_AES_128_GCM_SHA256];
206        let chosen = choose_ciphersuite_preferring_client(&client, &server);
207        assert!(chosen.is_some());
208        assert_eq!(chosen.unwrap(), TLS13_AES_128_GCM_SHA256);
209    }
210
211    #[test_log::test]
212    fn test_server_pref() {
213        let client = vec![
214            CipherSuite::TLS13_AES_128_GCM_SHA256,
215            CipherSuite::TLS13_AES_256_GCM_SHA384,
216        ];
217        let server = vec![TLS13_AES_256_GCM_SHA384, TLS13_AES_128_GCM_SHA256];
218        let chosen = choose_ciphersuite_preferring_server(&client, &server);
219        assert!(chosen.is_some());
220        assert_eq!(chosen.unwrap(), TLS13_AES_256_GCM_SHA384);
221    }
222
223    #[test_log::test]
224    fn test_pref_fails() {
225        assert!(choose_ciphersuite_preferring_client(
226            &[CipherSuite::TLS_NULL_WITH_NULL_NULL],
227            ALL_CIPHER_SUITES
228        )
229        .is_none());
230        assert!(choose_ciphersuite_preferring_server(
231            &[CipherSuite::TLS_NULL_WITH_NULL_NULL],
232            ALL_CIPHER_SUITES
233        )
234        .is_none());
235    }
236
237    #[test_log::test]
238    fn test_scs_is_debug() {
239        // println!("{:?}", ALL_CIPHER_SUITES);
240    }
241
242    #[test_log::test]
243    fn test_can_resume_to() {
244        assert!(TLS13_AES_128_GCM_SHA256
245            .tls13()
246            .unwrap()
247            .can_resume_from(crate::tls::rustls::tls13::TLS13_CHACHA20_POLY1305_SHA256_INTERNAL)
248            .is_some());
249        assert!(TLS13_AES_256_GCM_SHA384
250            .tls13()
251            .unwrap()
252            .can_resume_from(crate::tls::rustls::tls13::TLS13_CHACHA20_POLY1305_SHA256_INTERNAL)
253            .is_none());
254    }
255}