cipher_suites.mx raw
1 // Copyright 2010 The Go Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style
3 // license that can be found in the LICENSE file.
4
5 package tls
6
7 import (
8 "crypto"
9 "crypto/aes"
10 "crypto/cipher"
11 "crypto/des"
12 "crypto/hmac"
13 "crypto/internal/boring"
14 fipsaes "crypto/internal/fips140/aes"
15 "crypto/internal/fips140/aes/gcm"
16 "crypto/rc4"
17 "crypto/sha1"
18 "crypto/sha256"
19 "fmt"
20 "hash"
21 "internal/cpu"
22 "runtime"
23 _ "unsafe" // for linkname
24
25 "golang.org/x/crypto/chacha20poly1305"
26 )
27
28 // CipherSuite is a TLS cipher suite. Note that most functions in this package
29 // accept and expose cipher suite IDs instead of this type.
30 type CipherSuite struct {
31 ID uint16
32 Name []byte
33
34 // Supported versions is the list of TLS protocol versions that can
35 // negotiate this cipher suite.
36 SupportedVersions []uint16
37
38 // Insecure is true if the cipher suite has known security issues
39 // due to its primitives, design, or implementation.
40 Insecure bool
41 }
42
43 var (
44 supportedUpToTLS12 = []uint16{VersionTLS10, VersionTLS11, VersionTLS12}
45 supportedOnlyTLS12 = []uint16{VersionTLS12}
46 supportedOnlyTLS13 = []uint16{VersionTLS13}
47 )
48
49 // CipherSuites returns a list of cipher suites currently implemented by this
50 // package, excluding those with security issues, which are returned by
51 // [InsecureCipherSuites].
52 //
53 // The list is sorted by ID. Note that the default cipher suites selected by
54 // this package might depend on logic that can't be captured by a static list,
55 // and might not match those returned by this function.
56 func CipherSuites() []*CipherSuite {
57 return []*CipherSuite{
58 {TLS_AES_128_GCM_SHA256, "TLS_AES_128_GCM_SHA256", supportedOnlyTLS13, false},
59 {TLS_AES_256_GCM_SHA384, "TLS_AES_256_GCM_SHA384", supportedOnlyTLS13, false},
60 {TLS_CHACHA20_POLY1305_SHA256, "TLS_CHACHA20_POLY1305_SHA256", supportedOnlyTLS13, false},
61
62 {TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA, "TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA", supportedUpToTLS12, false},
63 {TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA, "TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA", supportedUpToTLS12, false},
64 {TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA, "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA", supportedUpToTLS12, false},
65 {TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA, "TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA", supportedUpToTLS12, false},
66 {TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256", supportedOnlyTLS12, false},
67 {TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384", supportedOnlyTLS12, false},
68 {TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256", supportedOnlyTLS12, false},
69 {TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384, "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384", supportedOnlyTLS12, false},
70 {TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256, "TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256", supportedOnlyTLS12, false},
71 {TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256, "TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256", supportedOnlyTLS12, false},
72 }
73 }
74
75 // InsecureCipherSuites returns a list of cipher suites currently implemented by
76 // this package and which have security issues.
77 //
78 // Most applications should not use the cipher suites in this list, and should
79 // only use those returned by [CipherSuites].
80 func InsecureCipherSuites() []*CipherSuite {
81 // This list includes legacy RSA kex, RC4, CBC_SHA256, and 3DES cipher
82 // suites. See cipherSuitesPreferenceOrder for details.
83 return []*CipherSuite{
84 {TLS_RSA_WITH_RC4_128_SHA, "TLS_RSA_WITH_RC4_128_SHA", supportedUpToTLS12, true},
85 {TLS_RSA_WITH_3DES_EDE_CBC_SHA, "TLS_RSA_WITH_3DES_EDE_CBC_SHA", supportedUpToTLS12, true},
86 {TLS_RSA_WITH_AES_128_CBC_SHA, "TLS_RSA_WITH_AES_128_CBC_SHA", supportedUpToTLS12, true},
87 {TLS_RSA_WITH_AES_256_CBC_SHA, "TLS_RSA_WITH_AES_256_CBC_SHA", supportedUpToTLS12, true},
88 {TLS_RSA_WITH_AES_128_CBC_SHA256, "TLS_RSA_WITH_AES_128_CBC_SHA256", supportedOnlyTLS12, true},
89 {TLS_RSA_WITH_AES_128_GCM_SHA256, "TLS_RSA_WITH_AES_128_GCM_SHA256", supportedOnlyTLS12, true},
90 {TLS_RSA_WITH_AES_256_GCM_SHA384, "TLS_RSA_WITH_AES_256_GCM_SHA384", supportedOnlyTLS12, true},
91 {TLS_ECDHE_ECDSA_WITH_RC4_128_SHA, "TLS_ECDHE_ECDSA_WITH_RC4_128_SHA", supportedUpToTLS12, true},
92 {TLS_ECDHE_RSA_WITH_RC4_128_SHA, "TLS_ECDHE_RSA_WITH_RC4_128_SHA", supportedUpToTLS12, true},
93 {TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA, "TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA", supportedUpToTLS12, true},
94 {TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256, "TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256", supportedOnlyTLS12, true},
95 {TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256, "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256", supportedOnlyTLS12, true},
96 }
97 }
98
99 // CipherSuiteName returns the standard name for the passed cipher suite ID
100 // (e.g. "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256"), or a fallback representation
101 // of the ID value if the cipher suite is not implemented by this package.
102 func CipherSuiteName(id uint16) []byte {
103 for _, c := range CipherSuites() {
104 if c.ID == id {
105 return c.Name
106 }
107 }
108 for _, c := range InsecureCipherSuites() {
109 if c.ID == id {
110 return c.Name
111 }
112 }
113 return fmt.Sprintf("0x%04X", id)
114 }
115
116 const (
117 // suiteECDHE indicates that the cipher suite involves elliptic curve
118 // Diffie-Hellman. This means that it should only be selected when the
119 // client indicates that it supports ECC with a curve and point format
120 // that we're happy with.
121 suiteECDHE = 1 << iota
122 // suiteECSign indicates that the cipher suite involves an ECDSA or
123 // EdDSA signature and therefore may only be selected when the server's
124 // certificate is ECDSA or EdDSA. If this is not set then the cipher suite
125 // is RSA based.
126 suiteECSign
127 // suiteTLS12 indicates that the cipher suite should only be advertised
128 // and accepted when using TLS 1.2.
129 suiteTLS12
130 // suiteSHA384 indicates that the cipher suite uses SHA384 as the
131 // handshake hash.
132 suiteSHA384
133 )
134
135 // A cipherSuite is a TLS 1.0–1.2 cipher suite, and defines the key exchange
136 // mechanism, as well as the cipher+MAC pair or the AEAD.
137 type cipherSuite struct {
138 id uint16
139 // the lengths, in bytes, of the key material needed for each component.
140 keyLen int
141 macLen int
142 ivLen int
143 ka func(version uint16) keyAgreement
144 // flags is a bitmask of the suite* values, above.
145 flags int
146 cipher func(key, iv []byte, isRead bool) any
147 mac func(key []byte) hash.Hash
148 aead func(key, fixedNonce []byte) aead
149 }
150
151 var cipherSuites = []*cipherSuite{ // TODO: replace with a map, since the order doesn't matter.
152 {TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256, 32, 0, 12, ecdheRSAKA, suiteECDHE | suiteTLS12, nil, nil, aeadChaCha20Poly1305},
153 {TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256, 32, 0, 12, ecdheECDSAKA, suiteECDHE | suiteECSign | suiteTLS12, nil, nil, aeadChaCha20Poly1305},
154 {TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, 16, 0, 4, ecdheRSAKA, suiteECDHE | suiteTLS12, nil, nil, aeadAESGCM},
155 {TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, 16, 0, 4, ecdheECDSAKA, suiteECDHE | suiteECSign | suiteTLS12, nil, nil, aeadAESGCM},
156 {TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384, 32, 0, 4, ecdheRSAKA, suiteECDHE | suiteTLS12 | suiteSHA384, nil, nil, aeadAESGCM},
157 {TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, 32, 0, 4, ecdheECDSAKA, suiteECDHE | suiteECSign | suiteTLS12 | suiteSHA384, nil, nil, aeadAESGCM},
158 {TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256, 16, 32, 16, ecdheRSAKA, suiteECDHE | suiteTLS12, cipherAES, macSHA256, nil},
159 {TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA, 16, 20, 16, ecdheRSAKA, suiteECDHE, cipherAES, macSHA1, nil},
160 {TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256, 16, 32, 16, ecdheECDSAKA, suiteECDHE | suiteECSign | suiteTLS12, cipherAES, macSHA256, nil},
161 {TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA, 16, 20, 16, ecdheECDSAKA, suiteECDHE | suiteECSign, cipherAES, macSHA1, nil},
162 {TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA, 32, 20, 16, ecdheRSAKA, suiteECDHE, cipherAES, macSHA1, nil},
163 {TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA, 32, 20, 16, ecdheECDSAKA, suiteECDHE | suiteECSign, cipherAES, macSHA1, nil},
164 {TLS_RSA_WITH_AES_128_GCM_SHA256, 16, 0, 4, rsaKA, suiteTLS12, nil, nil, aeadAESGCM},
165 {TLS_RSA_WITH_AES_256_GCM_SHA384, 32, 0, 4, rsaKA, suiteTLS12 | suiteSHA384, nil, nil, aeadAESGCM},
166 {TLS_RSA_WITH_AES_128_CBC_SHA256, 16, 32, 16, rsaKA, suiteTLS12, cipherAES, macSHA256, nil},
167 {TLS_RSA_WITH_AES_128_CBC_SHA, 16, 20, 16, rsaKA, 0, cipherAES, macSHA1, nil},
168 {TLS_RSA_WITH_AES_256_CBC_SHA, 32, 20, 16, rsaKA, 0, cipherAES, macSHA1, nil},
169 {TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA, 24, 20, 8, ecdheRSAKA, suiteECDHE, cipher3DES, macSHA1, nil},
170 {TLS_RSA_WITH_3DES_EDE_CBC_SHA, 24, 20, 8, rsaKA, 0, cipher3DES, macSHA1, nil},
171 {TLS_RSA_WITH_RC4_128_SHA, 16, 20, 0, rsaKA, 0, cipherRC4, macSHA1, nil},
172 {TLS_ECDHE_RSA_WITH_RC4_128_SHA, 16, 20, 0, ecdheRSAKA, suiteECDHE, cipherRC4, macSHA1, nil},
173 {TLS_ECDHE_ECDSA_WITH_RC4_128_SHA, 16, 20, 0, ecdheECDSAKA, suiteECDHE | suiteECSign, cipherRC4, macSHA1, nil},
174 }
175
176 // selectCipherSuite returns the first TLS 1.0–1.2 cipher suite from ids which
177 // is also in supportedIDs and passes the ok filter.
178 func selectCipherSuite(ids, supportedIDs []uint16, ok func(*cipherSuite) bool) *cipherSuite {
179 for _, id := range ids {
180 candidate := cipherSuiteByID(id)
181 if candidate == nil || !ok(candidate) {
182 continue
183 }
184
185 for _, suppID := range supportedIDs {
186 if id == suppID {
187 return candidate
188 }
189 }
190 }
191 return nil
192 }
193
194 // A cipherSuiteTLS13 defines only the pair of the AEAD algorithm and hash
195 // algorithm to be used with HKDF. See RFC 8446, Appendix B.4.
196 type cipherSuiteTLS13 struct {
197 id uint16
198 keyLen int
199 aead func(key, fixedNonce []byte) aead
200 hash crypto.Hash
201 }
202
203 // cipherSuitesTLS13 should be an internal detail,
204 // but widely used packages access it using linkname.
205 // Notable members of the hall of shame include:
206 // - github.com/quic-go/quic-go
207 // - github.com/sagernet/quic-go
208 //
209 // Do not remove or change the type signature.
210 // See go.dev/issue/67401.
211 //
212 //go:linkname cipherSuitesTLS13
213 var cipherSuitesTLS13 = []*cipherSuiteTLS13{ // TODO: replace with a map.
214 {TLS_AES_128_GCM_SHA256, 16, aeadAESGCMTLS13, crypto.SHA256},
215 {TLS_CHACHA20_POLY1305_SHA256, 32, aeadChaCha20Poly1305, crypto.SHA256},
216 {TLS_AES_256_GCM_SHA384, 32, aeadAESGCMTLS13, crypto.SHA384},
217 }
218
219 // cipherSuitesPreferenceOrder is the order in which we'll select (on the
220 // server) or advertise (on the client) TLS 1.0–1.2 cipher suites.
221 //
222 // Cipher suites are filtered but not reordered based on the application and
223 // peer's preferences, meaning we'll never select a suite lower in this list if
224 // any higher one is available. This makes it more defensible to keep weaker
225 // cipher suites enabled, especially on the server side where we get the last
226 // word, since there are no known downgrade attacks on cipher suites selection.
227 //
228 // The list is sorted by applying the following priority rules, stopping at the
229 // first (most important) applicable one:
230 //
231 // - Anything else comes before RC4
232 //
233 // RC4 has practically exploitable biases. See https://www.rc4nomore.com.
234 //
235 // - Anything else comes before CBC_SHA256
236 //
237 // SHA-256 variants of the CBC ciphersuites don't implement any Lucky13
238 // countermeasures. See https://www.isg.rhul.ac.uk/tls/Lucky13.html and
239 // https://www.imperialviolet.org/2013/02/04/luckythirteen.html.
240 //
241 // - Anything else comes before 3DES
242 //
243 // 3DES has 64-bit blocks, which makes it fundamentally susceptible to
244 // birthday attacks. See https://sweet32.info.
245 //
246 // - ECDHE comes before anything else
247 //
248 // Once we got the broken stuff out of the way, the most important
249 // property a cipher suite can have is forward secrecy. We don't
250 // implement FFDHE, so that means ECDHE.
251 //
252 // - AEADs come before CBC ciphers
253 //
254 // Even with Lucky13 countermeasures, MAC-then-Encrypt CBC cipher suites
255 // are fundamentally fragile, and suffered from an endless sequence of
256 // padding oracle attacks. See https://eprint.iacr.org/2015/1129,
257 // https://www.imperialviolet.org/2014/12/08/poodleagain.html, and
258 // https://blog.cloudflare.com/yet-another-padding-oracle-in-openssl-cbc-ciphersuites/.
259 //
260 // - AES comes before ChaCha20
261 //
262 // When AES hardware is available, AES-128-GCM and AES-256-GCM are faster
263 // than ChaCha20Poly1305.
264 //
265 // When AES hardware is not available, AES-128-GCM is one or more of: much
266 // slower, way more complex, and less safe (because not constant time)
267 // than ChaCha20Poly1305.
268 //
269 // We use this list if we think both peers have AES hardware, and
270 // cipherSuitesPreferenceOrderNoAES otherwise.
271 //
272 // - AES-128 comes before AES-256
273 //
274 // The only potential advantages of AES-256 are better multi-target
275 // margins, and hypothetical post-quantum properties. Neither apply to
276 // TLS, and AES-256 is slower due to its four extra rounds (which don't
277 // contribute to the advantages above).
278 //
279 // - ECDSA comes before RSA
280 //
281 // The relative order of ECDSA and RSA cipher suites doesn't matter,
282 // as they depend on the certificate. Pick one to get a stable order.
283 var cipherSuitesPreferenceOrder = []uint16{
284 // AEADs w/ ECDHE
285 TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
286 TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
287 TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256, TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256,
288
289 // CBC w/ ECDHE
290 TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,
291 TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,
292
293 // AEADs w/o ECDHE
294 TLS_RSA_WITH_AES_128_GCM_SHA256,
295 TLS_RSA_WITH_AES_256_GCM_SHA384,
296
297 // CBC w/o ECDHE
298 TLS_RSA_WITH_AES_128_CBC_SHA,
299 TLS_RSA_WITH_AES_256_CBC_SHA,
300
301 // 3DES
302 TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA,
303 TLS_RSA_WITH_3DES_EDE_CBC_SHA,
304
305 // CBC_SHA256
306 TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,
307 TLS_RSA_WITH_AES_128_CBC_SHA256,
308
309 // RC4
310 TLS_ECDHE_ECDSA_WITH_RC4_128_SHA, TLS_ECDHE_RSA_WITH_RC4_128_SHA,
311 TLS_RSA_WITH_RC4_128_SHA,
312 }
313
314 var cipherSuitesPreferenceOrderNoAES = []uint16{
315 // ChaCha20Poly1305
316 TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256, TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256,
317
318 // AES-GCM w/ ECDHE
319 TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
320 TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
321
322 // The rest of cipherSuitesPreferenceOrder.
323 TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,
324 TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,
325 TLS_RSA_WITH_AES_128_GCM_SHA256,
326 TLS_RSA_WITH_AES_256_GCM_SHA384,
327 TLS_RSA_WITH_AES_128_CBC_SHA,
328 TLS_RSA_WITH_AES_256_CBC_SHA,
329 TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA,
330 TLS_RSA_WITH_3DES_EDE_CBC_SHA,
331 TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,
332 TLS_RSA_WITH_AES_128_CBC_SHA256,
333 TLS_ECDHE_ECDSA_WITH_RC4_128_SHA, TLS_ECDHE_RSA_WITH_RC4_128_SHA,
334 TLS_RSA_WITH_RC4_128_SHA,
335 }
336
337 // disabledCipherSuites are not used unless explicitly listed in Config.CipherSuites.
338 var disabledCipherSuites = map[uint16]bool{
339 // CBC_SHA256
340 TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256: true,
341 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256: true,
342 TLS_RSA_WITH_AES_128_CBC_SHA256: true,
343
344 // RC4
345 TLS_ECDHE_ECDSA_WITH_RC4_128_SHA: true,
346 TLS_ECDHE_RSA_WITH_RC4_128_SHA: true,
347 TLS_RSA_WITH_RC4_128_SHA: true,
348 }
349
350 // rsaKexCiphers contains the ciphers which use RSA based key exchange,
351 // which we also disable by default unless a GODEBUG is set.
352 var rsaKexCiphers = map[uint16]bool{
353 TLS_RSA_WITH_RC4_128_SHA: true,
354 TLS_RSA_WITH_3DES_EDE_CBC_SHA: true,
355 TLS_RSA_WITH_AES_128_CBC_SHA: true,
356 TLS_RSA_WITH_AES_256_CBC_SHA: true,
357 TLS_RSA_WITH_AES_128_CBC_SHA256: true,
358 TLS_RSA_WITH_AES_128_GCM_SHA256: true,
359 TLS_RSA_WITH_AES_256_GCM_SHA384: true,
360 }
361
362 // tdesCiphers contains 3DES ciphers,
363 // which we also disable by default unless a GODEBUG is set.
364 var tdesCiphers = map[uint16]bool{
365 TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA: true,
366 TLS_RSA_WITH_3DES_EDE_CBC_SHA: true,
367 }
368
369 var (
370 // Keep in sync with crypto/internal/fips140/aes/gcm.supportsAESGCM.
371 hasGCMAsmAMD64 = cpu.X86.HasAES && cpu.X86.HasPCLMULQDQ && cpu.X86.HasSSE41 && cpu.X86.HasSSSE3
372 hasGCMAsmARM64 = cpu.ARM64.HasAES && cpu.ARM64.HasPMULL
373 hasGCMAsmS390X = cpu.S390X.HasAES && cpu.S390X.HasAESCTR && cpu.S390X.HasGHASH
374 hasGCMAsmPPC64 = runtime.GOARCH == "ppc64" || runtime.GOARCH == "ppc64le"
375
376 hasAESGCMHardwareSupport = hasGCMAsmAMD64 || hasGCMAsmARM64 || hasGCMAsmS390X || hasGCMAsmPPC64
377 )
378
379 var aesgcmCiphers = map[uint16]bool{
380 // TLS 1.2
381 TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256: true,
382 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384: true,
383 TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256: true,
384 TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384: true,
385 // TLS 1.3
386 TLS_AES_128_GCM_SHA256: true,
387 TLS_AES_256_GCM_SHA384: true,
388 }
389
390 // isAESGCMPreferred returns whether we have hardware support for AES-GCM, and the
391 // first known cipher in the peer's preference list is an AES-GCM cipher,
392 // implying the peer also has hardware support for it.
393 func isAESGCMPreferred(ciphers []uint16) bool {
394 if !hasAESGCMHardwareSupport {
395 return false
396 }
397 for _, cID := range ciphers {
398 if c := cipherSuiteByID(cID); c != nil {
399 return aesgcmCiphers[cID]
400 }
401 if c := cipherSuiteTLS13ByID(cID); c != nil {
402 return aesgcmCiphers[cID]
403 }
404 }
405 return false
406 }
407
408 func cipherRC4(key, iv []byte, isRead bool) any {
409 cipher, _ := rc4.NewCipher(key)
410 return cipher
411 }
412
413 func cipher3DES(key, iv []byte, isRead bool) any {
414 block, _ := des.NewTripleDESCipher(key)
415 if isRead {
416 return cipher.NewCBCDecrypter(block, iv)
417 }
418 return cipher.NewCBCEncrypter(block, iv)
419 }
420
421 func cipherAES(key, iv []byte, isRead bool) any {
422 block, _ := aes.NewCipher(key)
423 if isRead {
424 return cipher.NewCBCDecrypter(block, iv)
425 }
426 return cipher.NewCBCEncrypter(block, iv)
427 }
428
429 // macSHA1 returns a SHA-1 based constant time MAC.
430 func macSHA1(key []byte) hash.Hash {
431 h := sha1.New
432 // The BoringCrypto SHA1 does not have a constant-time
433 // checksum function, so don't try to use it.
434 if !boring.Enabled {
435 h = newConstantTimeHash(h)
436 }
437 return hmac.New(h, key)
438 }
439
440 // macSHA256 returns a SHA-256 based MAC. This is only supported in TLS 1.2 and
441 // is currently only used in disabled-by-default cipher suites.
442 func macSHA256(key []byte) hash.Hash {
443 return hmac.New(sha256.New, key)
444 }
445
446 type aead interface {
447 cipher.AEAD
448
449 // explicitNonceLen returns the number of bytes of explicit nonce
450 // included in each record. This is eight for older AEADs and
451 // zero for modern ones.
452 explicitNonceLen() int
453 }
454
455 const (
456 aeadNonceLength = 12
457 noncePrefixLength = 4
458 )
459
460 // prefixNonceAEAD wraps an AEAD and prefixes a fixed portion of the nonce to
461 // each call.
462 type prefixNonceAEAD struct {
463 // nonce contains the fixed part of the nonce in the first four bytes.
464 nonce [aeadNonceLength]byte
465 aead cipher.AEAD
466 }
467
468 func (f *prefixNonceAEAD) NonceSize() int { return aeadNonceLength - noncePrefixLength }
469 func (f *prefixNonceAEAD) Overhead() int { return f.aead.Overhead() }
470 func (f *prefixNonceAEAD) explicitNonceLen() int { return f.NonceSize() }
471
472 func (f *prefixNonceAEAD) Seal(out, nonce, plaintext, additionalData []byte) []byte {
473 copy(f.nonce[4:], nonce)
474 return f.aead.Seal(out, f.nonce[:], plaintext, additionalData)
475 }
476
477 func (f *prefixNonceAEAD) Open(out, nonce, ciphertext, additionalData []byte) ([]byte, error) {
478 copy(f.nonce[4:], nonce)
479 return f.aead.Open(out, f.nonce[:], ciphertext, additionalData)
480 }
481
482 // xorNonceAEAD wraps an AEAD by XORing in a fixed pattern to the nonce
483 // before each call.
484 type xorNonceAEAD struct {
485 nonceMask [aeadNonceLength]byte
486 aead cipher.AEAD
487 }
488
489 func (f *xorNonceAEAD) NonceSize() int { return 8 } // 64-bit sequence number
490 func (f *xorNonceAEAD) Overhead() int { return f.aead.Overhead() }
491 func (f *xorNonceAEAD) explicitNonceLen() int { return 0 }
492
493 func (f *xorNonceAEAD) Seal(out, nonce, plaintext, additionalData []byte) []byte {
494 for i, b := range nonce {
495 f.nonceMask[4+i] ^= b
496 }
497 result := f.aead.Seal(out, f.nonceMask[:], plaintext, additionalData)
498 for i, b := range nonce {
499 f.nonceMask[4+i] ^= b
500 }
501
502 return result
503 }
504
505 func (f *xorNonceAEAD) Open(out, nonce, ciphertext, additionalData []byte) ([]byte, error) {
506 for i, b := range nonce {
507 f.nonceMask[4+i] ^= b
508 }
509 result, err := f.aead.Open(out, f.nonceMask[:], ciphertext, additionalData)
510 for i, b := range nonce {
511 f.nonceMask[4+i] ^= b
512 }
513
514 return result, err
515 }
516
517 func aeadAESGCM(key, noncePrefix []byte) aead {
518 if len(noncePrefix) != noncePrefixLength {
519 panic("tls: internal error: wrong nonce length")
520 }
521 aes, err := aes.NewCipher(key)
522 if err != nil {
523 panic(err)
524 }
525 var aead cipher.AEAD
526 if boring.Enabled {
527 aead, err = boring.NewGCMTLS(aes)
528 } else {
529 boring.Unreachable()
530 aead, err = gcm.NewGCMForTLS12(aes.(*fipsaes.Block))
531 }
532 if err != nil {
533 panic(err)
534 }
535
536 ret := &prefixNonceAEAD{aead: aead}
537 copy(ret.nonce[:], noncePrefix)
538 return ret
539 }
540
541 // aeadAESGCMTLS13 should be an internal detail,
542 // but widely used packages access it using linkname.
543 // Notable members of the hall of shame include:
544 // - github.com/xtls/xray-core
545 // - github.com/v2fly/v2ray-core
546 //
547 // Do not remove or change the type signature.
548 // See go.dev/issue/67401.
549 //
550 //go:linkname aeadAESGCMTLS13
551 func aeadAESGCMTLS13(key, nonceMask []byte) aead {
552 if len(nonceMask) != aeadNonceLength {
553 panic("tls: internal error: wrong nonce length")
554 }
555 aes, err := aes.NewCipher(key)
556 if err != nil {
557 panic(err)
558 }
559 var aead cipher.AEAD
560 if boring.Enabled {
561 aead, err = boring.NewGCMTLS13(aes)
562 } else {
563 boring.Unreachable()
564 aead, err = gcm.NewGCMForTLS13(aes.(*fipsaes.Block))
565 }
566 if err != nil {
567 panic(err)
568 }
569
570 ret := &xorNonceAEAD{aead: aead}
571 copy(ret.nonceMask[:], nonceMask)
572 return ret
573 }
574
575 func aeadChaCha20Poly1305(key, nonceMask []byte) aead {
576 if len(nonceMask) != aeadNonceLength {
577 panic("tls: internal error: wrong nonce length")
578 }
579 aead, err := chacha20poly1305.New(key)
580 if err != nil {
581 panic(err)
582 }
583
584 ret := &xorNonceAEAD{aead: aead}
585 copy(ret.nonceMask[:], nonceMask)
586 return ret
587 }
588
589 type constantTimeHash interface {
590 hash.Hash
591 ConstantTimeSum(b []byte) []byte
592 }
593
594 // cthWrapper wraps any hash.Hash that implements ConstantTimeSum, and replaces
595 // with that all calls to Sum. It's used to obtain a ConstantTimeSum-based HMAC.
596 type cthWrapper struct {
597 h constantTimeHash
598 }
599
600 func (c *cthWrapper) Size() int { return c.h.Size() }
601 func (c *cthWrapper) BlockSize() int { return c.h.BlockSize() }
602 func (c *cthWrapper) Reset() { c.h.Reset() }
603 func (c *cthWrapper) Write(p []byte) (int, error) { return c.h.Write(p) }
604 func (c *cthWrapper) Sum(b []byte) []byte { return c.h.ConstantTimeSum(b) }
605
606 func newConstantTimeHash(h func() hash.Hash) func() hash.Hash {
607 boring.Unreachable()
608 return func() hash.Hash {
609 return &cthWrapper{h().(constantTimeHash)}
610 }
611 }
612
613 // tls10MAC implements the TLS 1.0 MAC function. RFC 2246, Section 6.2.3.
614 func tls10MAC(h hash.Hash, out, seq, header, data, extra []byte) []byte {
615 h.Reset()
616 h.Write(seq)
617 h.Write(header)
618 h.Write(data)
619 res := h.Sum(out)
620 if extra != nil {
621 h.Write(extra)
622 }
623 return res
624 }
625
626 func rsaKA(version uint16) keyAgreement {
627 return rsaKeyAgreement{}
628 }
629
630 func ecdheECDSAKA(version uint16) keyAgreement {
631 return &ecdheKeyAgreement{
632 isRSA: false,
633 version: version,
634 }
635 }
636
637 func ecdheRSAKA(version uint16) keyAgreement {
638 return &ecdheKeyAgreement{
639 isRSA: true,
640 version: version,
641 }
642 }
643
644 // mutualCipherSuite returns a cipherSuite given a list of supported
645 // ciphersuites and the id requested by the peer.
646 func mutualCipherSuite(have []uint16, want uint16) *cipherSuite {
647 for _, id := range have {
648 if id == want {
649 return cipherSuiteByID(id)
650 }
651 }
652 return nil
653 }
654
655 func cipherSuiteByID(id uint16) *cipherSuite {
656 for _, cipherSuite := range cipherSuites {
657 if cipherSuite.id == id {
658 return cipherSuite
659 }
660 }
661 return nil
662 }
663
664 func mutualCipherSuiteTLS13(have []uint16, want uint16) *cipherSuiteTLS13 {
665 for _, id := range have {
666 if id == want {
667 return cipherSuiteTLS13ByID(id)
668 }
669 }
670 return nil
671 }
672
673 func cipherSuiteTLS13ByID(id uint16) *cipherSuiteTLS13 {
674 for _, cipherSuite := range cipherSuitesTLS13 {
675 if cipherSuite.id == id {
676 return cipherSuite
677 }
678 }
679 return nil
680 }
681
682 // A list of cipher suite IDs that are, or have been, implemented by this
683 // package.
684 //
685 // See https://www.iana.org/assignments/tls-parameters/tls-parameters.xml
686 const (
687 // TLS 1.0 - 1.2 cipher suites.
688 TLS_RSA_WITH_RC4_128_SHA uint16 = 0x0005
689 TLS_RSA_WITH_3DES_EDE_CBC_SHA uint16 = 0x000a
690 TLS_RSA_WITH_AES_128_CBC_SHA uint16 = 0x002f
691 TLS_RSA_WITH_AES_256_CBC_SHA uint16 = 0x0035
692 TLS_RSA_WITH_AES_128_CBC_SHA256 uint16 = 0x003c
693 TLS_RSA_WITH_AES_128_GCM_SHA256 uint16 = 0x009c
694 TLS_RSA_WITH_AES_256_GCM_SHA384 uint16 = 0x009d
695 TLS_ECDHE_ECDSA_WITH_RC4_128_SHA uint16 = 0xc007
696 TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA uint16 = 0xc009
697 TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA uint16 = 0xc00a
698 TLS_ECDHE_RSA_WITH_RC4_128_SHA uint16 = 0xc011
699 TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA uint16 = 0xc012
700 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA uint16 = 0xc013
701 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA uint16 = 0xc014
702 TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 uint16 = 0xc023
703 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 uint16 = 0xc027
704 TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 uint16 = 0xc02f
705 TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 uint16 = 0xc02b
706 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 uint16 = 0xc030
707 TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 uint16 = 0xc02c
708 TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 uint16 = 0xcca8
709 TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 uint16 = 0xcca9
710
711 // TLS 1.3 cipher suites.
712 TLS_AES_128_GCM_SHA256 uint16 = 0x1301
713 TLS_AES_256_GCM_SHA384 uint16 = 0x1302
714 TLS_CHACHA20_POLY1305_SHA256 uint16 = 0x1303
715
716 // TLS_FALLBACK_SCSV isn't a standard cipher suite but an indicator
717 // that the client is doing version fallback. See RFC 7507.
718 TLS_FALLBACK_SCSV uint16 = 0x5600
719
720 // Legacy names for the corresponding cipher suites with the correct _SHA256
721 // suffix, retained for backward compatibility.
722 TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 = TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
723 TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305 = TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
724 )
725