Source file src/crypto/tls/common.go
1 // Copyright 2009 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 "bytes" 9 "container/list" 10 "context" 11 "crypto" 12 "crypto/ecdsa" 13 "crypto/ed25519" 14 "crypto/elliptic" 15 "crypto/rand" 16 "crypto/rsa" 17 "crypto/sha512" 18 "crypto/tls/internal/fips140tls" 19 "crypto/x509" 20 "errors" 21 "fmt" 22 "internal/godebug" 23 "io" 24 "net" 25 "runtime" 26 "slices" 27 "strings" 28 "sync" 29 "time" 30 _ "unsafe" // for linkname 31 ) 32 33 const ( 34 VersionTLS10 = 0x0301 35 VersionTLS11 = 0x0302 36 VersionTLS12 = 0x0303 37 VersionTLS13 = 0x0304 38 39 // Deprecated: SSLv3 is cryptographically broken, and is no longer 40 // supported by this package. See golang.org/issue/32716. 41 VersionSSL30 = 0x0300 42 ) 43 44 // VersionName returns the name for the provided TLS version number 45 // (e.g. "TLS 1.3"), or a fallback representation of the value if the 46 // version is not implemented by this package. 47 func VersionName(version uint16) string { 48 switch version { 49 case VersionSSL30: 50 return "SSLv3" 51 case VersionTLS10: 52 return "TLS 1.0" 53 case VersionTLS11: 54 return "TLS 1.1" 55 case VersionTLS12: 56 return "TLS 1.2" 57 case VersionTLS13: 58 return "TLS 1.3" 59 default: 60 return fmt.Sprintf("0x%04X", version) 61 } 62 } 63 64 const ( 65 maxPlaintext = 16384 // maximum plaintext payload length 66 maxCiphertext = 16384 + 2048 // maximum ciphertext payload length 67 maxCiphertextTLS13 = 16384 + 256 // maximum ciphertext length in TLS 1.3 68 recordHeaderLen = 5 // record header length 69 maxHandshake = 65536 // maximum handshake we support (protocol max is 16 MB) 70 maxHandshakeCertificateMsg = 262144 // maximum certificate message size (256 KiB) 71 maxUselessRecords = 16 // maximum number of consecutive non-advancing records 72 ) 73 74 // TLS record types. 75 type recordType uint8 76 77 const ( 78 recordTypeChangeCipherSpec recordType = 20 79 recordTypeAlert recordType = 21 80 recordTypeHandshake recordType = 22 81 recordTypeApplicationData recordType = 23 82 ) 83 84 // TLS handshake message types. 85 const ( 86 typeHelloRequest uint8 = 0 87 typeClientHello uint8 = 1 88 typeServerHello uint8 = 2 89 typeNewSessionTicket uint8 = 4 90 typeEndOfEarlyData uint8 = 5 91 typeEncryptedExtensions uint8 = 8 92 typeCertificate uint8 = 11 93 typeServerKeyExchange uint8 = 12 94 typeCertificateRequest uint8 = 13 95 typeServerHelloDone uint8 = 14 96 typeCertificateVerify uint8 = 15 97 typeClientKeyExchange uint8 = 16 98 typeFinished uint8 = 20 99 typeCertificateStatus uint8 = 22 100 typeKeyUpdate uint8 = 24 101 typeMessageHash uint8 = 254 // synthetic message 102 ) 103 104 // TLS compression types. 105 const ( 106 compressionNone uint8 = 0 107 ) 108 109 // TLS extension numbers 110 const ( 111 extensionServerName uint16 = 0 112 extensionStatusRequest uint16 = 5 113 extensionSupportedCurves uint16 = 10 // supported_groups in TLS 1.3, see RFC 8446, Section 4.2.7 114 extensionSupportedPoints uint16 = 11 115 extensionSignatureAlgorithms uint16 = 13 116 extensionALPN uint16 = 16 117 extensionSCT uint16 = 18 118 extensionExtendedMasterSecret uint16 = 23 119 extensionSessionTicket uint16 = 35 120 extensionPreSharedKey uint16 = 41 121 extensionEarlyData uint16 = 42 122 extensionSupportedVersions uint16 = 43 123 extensionCookie uint16 = 44 124 extensionPSKModes uint16 = 45 125 extensionCertificateAuthorities uint16 = 47 126 extensionSignatureAlgorithmsCert uint16 = 50 127 extensionKeyShare uint16 = 51 128 extensionQUICTransportParameters uint16 = 57 129 extensionRenegotiationInfo uint16 = 0xff01 130 extensionECHOuterExtensions uint16 = 0xfd00 131 extensionEncryptedClientHello uint16 = 0xfe0d 132 ) 133 134 // TLS signaling cipher suite values 135 const ( 136 scsvRenegotiation uint16 = 0x00ff 137 ) 138 139 // CurveID is the type of a TLS identifier for a key exchange mechanism. See 140 // https://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-8. 141 // 142 // In TLS 1.2, this registry used to support only elliptic curves. In TLS 1.3, 143 // it was extended to other groups and renamed NamedGroup. See RFC 8446, Section 144 // 4.2.7. It was then also extended to other mechanisms, such as hybrid 145 // post-quantum KEMs. 146 type CurveID uint16 147 148 const ( 149 CurveP256 CurveID = 23 150 CurveP384 CurveID = 24 151 CurveP521 CurveID = 25 152 X25519 CurveID = 29 153 X25519MLKEM768 CurveID = 4588 154 ) 155 156 func isTLS13OnlyKeyExchange(curve CurveID) bool { 157 return curve == X25519MLKEM768 158 } 159 160 func isPQKeyExchange(curve CurveID) bool { 161 return curve == X25519MLKEM768 162 } 163 164 // TLS 1.3 Key Share. See RFC 8446, Section 4.2.8. 165 type keyShare struct { 166 group CurveID 167 data []byte 168 } 169 170 // TLS 1.3 PSK Key Exchange Modes. See RFC 8446, Section 4.2.9. 171 const ( 172 pskModePlain uint8 = 0 173 pskModeDHE uint8 = 1 174 ) 175 176 // TLS 1.3 PSK Identity. Can be a Session Ticket, or a reference to a saved 177 // session. See RFC 8446, Section 4.2.11. 178 type pskIdentity struct { 179 label []byte 180 obfuscatedTicketAge uint32 181 } 182 183 // TLS Elliptic Curve Point Formats 184 // https://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-9 185 const ( 186 pointFormatUncompressed uint8 = 0 187 ) 188 189 // TLS CertificateStatusType (RFC 3546) 190 const ( 191 statusTypeOCSP uint8 = 1 192 ) 193 194 // Certificate types (for certificateRequestMsg) 195 const ( 196 certTypeRSASign = 1 197 certTypeECDSASign = 64 // ECDSA or EdDSA keys, see RFC 8422, Section 3. 198 ) 199 200 // Signature algorithms (for internal signaling use). Starting at 225 to avoid overlap with 201 // TLS 1.2 codepoints (RFC 5246, Appendix A.4.1), with which these have nothing to do. 202 const ( 203 signaturePKCS1v15 uint8 = iota + 225 204 signatureRSAPSS 205 signatureECDSA 206 signatureEd25519 207 ) 208 209 // directSigning is a standard Hash value that signals that no pre-hashing 210 // should be performed, and that the input should be signed directly. It is the 211 // hash function associated with the Ed25519 signature scheme. 212 var directSigning crypto.Hash = 0 213 214 // helloRetryRequestRandom is set as the Random value of a ServerHello 215 // to signal that the message is actually a HelloRetryRequest. 216 var helloRetryRequestRandom = []byte{ // See RFC 8446, Section 4.1.3. 217 0xCF, 0x21, 0xAD, 0x74, 0xE5, 0x9A, 0x61, 0x11, 218 0xBE, 0x1D, 0x8C, 0x02, 0x1E, 0x65, 0xB8, 0x91, 219 0xC2, 0xA2, 0x11, 0x16, 0x7A, 0xBB, 0x8C, 0x5E, 220 0x07, 0x9E, 0x09, 0xE2, 0xC8, 0xA8, 0x33, 0x9C, 221 } 222 223 const ( 224 // downgradeCanaryTLS12 or downgradeCanaryTLS11 is embedded in the server 225 // random as a downgrade protection if the server would be capable of 226 // negotiating a higher version. See RFC 8446, Section 4.1.3. 227 downgradeCanaryTLS12 = "DOWNGRD\x01" 228 downgradeCanaryTLS11 = "DOWNGRD\x00" 229 ) 230 231 // testingOnlyForceDowngradeCanary is set in tests to force the server side to 232 // include downgrade canaries even if it's using its highers supported version. 233 var testingOnlyForceDowngradeCanary bool 234 235 // ConnectionState records basic TLS details about the connection. 236 type ConnectionState struct { 237 // Version is the TLS version used by the connection (e.g. VersionTLS12). 238 Version uint16 239 240 // HandshakeComplete is true if the handshake has concluded. 241 HandshakeComplete bool 242 243 // DidResume is true if this connection was successfully resumed from a 244 // previous session with a session ticket or similar mechanism. 245 DidResume bool 246 247 // CipherSuite is the cipher suite negotiated for the connection (e.g. 248 // TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, TLS_AES_128_GCM_SHA256). 249 CipherSuite uint16 250 251 // CurveID is the key exchange mechanism used for the connection. The name 252 // refers to elliptic curves for legacy reasons, see [CurveID]. If a legacy 253 // RSA key exchange is used, this value is zero. 254 CurveID CurveID 255 256 // NegotiatedProtocol is the application protocol negotiated with ALPN. 257 NegotiatedProtocol string 258 259 // NegotiatedProtocolIsMutual used to indicate a mutual NPN negotiation. 260 // 261 // Deprecated: this value is always true. 262 NegotiatedProtocolIsMutual bool 263 264 // ServerName is the value of the Server Name Indication extension sent by 265 // the client. It's available both on the server and on the client side. 266 ServerName string 267 268 // PeerCertificates are the parsed certificates sent by the peer, in the 269 // order in which they were sent. The first element is the leaf certificate 270 // that the connection is verified against. 271 // 272 // On the client side, it can't be empty. On the server side, it can be 273 // empty if Config.ClientAuth is not RequireAnyClientCert or 274 // RequireAndVerifyClientCert. 275 // 276 // PeerCertificates and its contents should not be modified. 277 PeerCertificates []*x509.Certificate 278 279 // VerifiedChains is a list of one or more chains where the first element is 280 // PeerCertificates[0] and the last element is from Config.RootCAs (on the 281 // client side) or Config.ClientCAs (on the server side). 282 // 283 // On the client side, it's set if Config.InsecureSkipVerify is false. On 284 // the server side, it's set if Config.ClientAuth is VerifyClientCertIfGiven 285 // (and the peer provided a certificate) or RequireAndVerifyClientCert. 286 // 287 // VerifiedChains and its contents should not be modified. 288 VerifiedChains [][]*x509.Certificate 289 290 // SignedCertificateTimestamps is a list of SCTs provided by the peer 291 // through the TLS handshake for the leaf certificate, if any. 292 SignedCertificateTimestamps [][]byte 293 294 // OCSPResponse is a stapled Online Certificate Status Protocol (OCSP) 295 // response provided by the peer for the leaf certificate, if any. 296 OCSPResponse []byte 297 298 // TLSUnique contains the "tls-unique" channel binding value (see RFC 5929, 299 // Section 3). This value will be nil for TLS 1.3 connections and for 300 // resumed connections that don't support Extended Master Secret (RFC 7627). 301 TLSUnique []byte 302 303 // ECHAccepted indicates if Encrypted Client Hello was offered by the client 304 // and accepted by the server. Currently, ECH is supported only on the 305 // client side. 306 ECHAccepted bool 307 308 // ekm is a closure exposed via ExportKeyingMaterial. 309 ekm func(label string, context []byte, length int) ([]byte, error) 310 311 // testingOnlyDidHRR is true if a HelloRetryRequest was sent/received. 312 testingOnlyDidHRR bool 313 314 // testingOnlyPeerSignatureAlgorithm is the signature algorithm used by the 315 // peer to sign the handshake. It is not set for resumed connections. 316 testingOnlyPeerSignatureAlgorithm SignatureScheme 317 } 318 319 // ExportKeyingMaterial returns length bytes of exported key material in a new 320 // slice as defined in RFC 5705. If context is nil, it is not used as part of 321 // the seed. If the connection was set to allow renegotiation via 322 // Config.Renegotiation, or if the connections supports neither TLS 1.3 nor 323 // Extended Master Secret, this function will return an error. 324 // 325 // Exporting key material without Extended Master Secret or TLS 1.3 was disabled 326 // in Go 1.22 due to security issues (see the Security Considerations sections 327 // of RFC 5705 and RFC 7627), but can be re-enabled with the GODEBUG setting 328 // tlsunsafeekm=1. 329 func (cs *ConnectionState) ExportKeyingMaterial(label string, context []byte, length int) ([]byte, error) { 330 return cs.ekm(label, context, length) 331 } 332 333 // ClientAuthType declares the policy the server will follow for 334 // TLS Client Authentication. 335 type ClientAuthType int 336 337 const ( 338 // NoClientCert indicates that no client certificate should be requested 339 // during the handshake, and if any certificates are sent they will not 340 // be verified. 341 NoClientCert ClientAuthType = iota 342 // RequestClientCert indicates that a client certificate should be requested 343 // during the handshake, but does not require that the client send any 344 // certificates. 345 RequestClientCert 346 // RequireAnyClientCert indicates that a client certificate should be requested 347 // during the handshake, and that at least one certificate is required to be 348 // sent by the client, but that certificate is not required to be valid. 349 RequireAnyClientCert 350 // VerifyClientCertIfGiven indicates that a client certificate should be requested 351 // during the handshake, but does not require that the client sends a 352 // certificate. If the client does send a certificate it is required to be 353 // valid. 354 VerifyClientCertIfGiven 355 // RequireAndVerifyClientCert indicates that a client certificate should be requested 356 // during the handshake, and that at least one valid certificate is required 357 // to be sent by the client. 358 RequireAndVerifyClientCert 359 ) 360 361 // requiresClientCert reports whether the ClientAuthType requires a client 362 // certificate to be provided. 363 func requiresClientCert(c ClientAuthType) bool { 364 switch c { 365 case RequireAnyClientCert, RequireAndVerifyClientCert: 366 return true 367 default: 368 return false 369 } 370 } 371 372 // ClientSessionCache is a cache of ClientSessionState objects that can be used 373 // by a client to resume a TLS session with a given server. ClientSessionCache 374 // implementations should expect to be called concurrently from different 375 // goroutines. Up to TLS 1.2, only ticket-based resumption is supported, not 376 // SessionID-based resumption. In TLS 1.3 they were merged into PSK modes, which 377 // are supported via this interface. 378 type ClientSessionCache interface { 379 // Get searches for a ClientSessionState associated with the given key. 380 // On return, ok is true if one was found. 381 Get(sessionKey string) (session *ClientSessionState, ok bool) 382 383 // Put adds the ClientSessionState to the cache with the given key. It might 384 // get called multiple times in a connection if a TLS 1.3 server provides 385 // more than one session ticket. If called with a nil *ClientSessionState, 386 // it should remove the cache entry. 387 Put(sessionKey string, cs *ClientSessionState) 388 } 389 390 //go:generate stringer -linecomment -type=SignatureScheme,CurveID,ClientAuthType -output=common_string.go 391 392 // SignatureScheme identifies a signature algorithm supported by TLS. See 393 // RFC 8446, Section 4.2.3. 394 type SignatureScheme uint16 395 396 const ( 397 // RSASSA-PKCS1-v1_5 algorithms. 398 PKCS1WithSHA256 SignatureScheme = 0x0401 399 PKCS1WithSHA384 SignatureScheme = 0x0501 400 PKCS1WithSHA512 SignatureScheme = 0x0601 401 402 // RSASSA-PSS algorithms with public key OID rsaEncryption. 403 PSSWithSHA256 SignatureScheme = 0x0804 404 PSSWithSHA384 SignatureScheme = 0x0805 405 PSSWithSHA512 SignatureScheme = 0x0806 406 407 // ECDSA algorithms. Only constrained to a specific curve in TLS 1.3. 408 ECDSAWithP256AndSHA256 SignatureScheme = 0x0403 409 ECDSAWithP384AndSHA384 SignatureScheme = 0x0503 410 ECDSAWithP521AndSHA512 SignatureScheme = 0x0603 411 412 // EdDSA algorithms. 413 Ed25519 SignatureScheme = 0x0807 414 415 // Legacy signature and hash algorithms for TLS 1.2. 416 PKCS1WithSHA1 SignatureScheme = 0x0201 417 ECDSAWithSHA1 SignatureScheme = 0x0203 418 ) 419 420 // ClientHelloInfo contains information from a ClientHello message in order to 421 // guide application logic in the GetCertificate and GetConfigForClient callbacks. 422 type ClientHelloInfo struct { 423 // CipherSuites lists the CipherSuites supported by the client (e.g. 424 // TLS_AES_128_GCM_SHA256, TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256). 425 CipherSuites []uint16 426 427 // ServerName indicates the name of the server requested by the client 428 // in order to support virtual hosting. ServerName is only set if the 429 // client is using SNI (see RFC 4366, Section 3.1). 430 ServerName string 431 432 // SupportedCurves lists the key exchange mechanisms supported by the 433 // client. It was renamed to "supported groups" in TLS 1.3, see RFC 8446, 434 // Section 4.2.7 and [CurveID]. 435 // 436 // SupportedCurves may be nil in TLS 1.2 and lower if the Supported Elliptic 437 // Curves Extension is not being used (see RFC 4492, Section 5.1.1). 438 SupportedCurves []CurveID 439 440 // SupportedPoints lists the point formats supported by the client. 441 // SupportedPoints is set only if the Supported Point Formats Extension 442 // is being used (see RFC 4492, Section 5.1.2). 443 SupportedPoints []uint8 444 445 // SignatureSchemes lists the signature and hash schemes that the client 446 // is willing to verify. SignatureSchemes is set only if the Signature 447 // Algorithms Extension is being used (see RFC 5246, Section 7.4.1.4.1). 448 SignatureSchemes []SignatureScheme 449 450 // SupportedProtos lists the application protocols supported by the client. 451 // SupportedProtos is set only if the Application-Layer Protocol 452 // Negotiation Extension is being used (see RFC 7301, Section 3.1). 453 // 454 // Servers can select a protocol by setting Config.NextProtos in a 455 // GetConfigForClient return value. 456 SupportedProtos []string 457 458 // SupportedVersions lists the TLS versions supported by the client. 459 // For TLS versions less than 1.3, this is extrapolated from the max 460 // version advertised by the client, so values other than the greatest 461 // might be rejected if used. 462 SupportedVersions []uint16 463 464 // Extensions lists the IDs of the extensions presented by the client 465 // in the ClientHello. 466 Extensions []uint16 467 468 // Conn is the underlying net.Conn for the connection. Do not read 469 // from, or write to, this connection; that will cause the TLS 470 // connection to fail. 471 Conn net.Conn 472 473 // config is embedded by the GetCertificate or GetConfigForClient caller, 474 // for use with SupportsCertificate. 475 config *Config 476 477 // ctx is the context of the handshake that is in progress. 478 ctx context.Context 479 } 480 481 // Context returns the context of the handshake that is in progress. 482 // This context is a child of the context passed to HandshakeContext, 483 // if any, and is canceled when the handshake concludes. 484 func (c *ClientHelloInfo) Context() context.Context { 485 return c.ctx 486 } 487 488 // CertificateRequestInfo contains information from a server's 489 // CertificateRequest message, which is used to demand a certificate and proof 490 // of control from a client. 491 type CertificateRequestInfo struct { 492 // AcceptableCAs contains zero or more, DER-encoded, X.501 493 // Distinguished Names. These are the names of root or intermediate CAs 494 // that the server wishes the returned certificate to be signed by. An 495 // empty slice indicates that the server has no preference. 496 AcceptableCAs [][]byte 497 498 // SignatureSchemes lists the signature schemes that the server is 499 // willing to verify. 500 SignatureSchemes []SignatureScheme 501 502 // Version is the TLS version that was negotiated for this connection. 503 Version uint16 504 505 // ctx is the context of the handshake that is in progress. 506 ctx context.Context 507 } 508 509 // Context returns the context of the handshake that is in progress. 510 // This context is a child of the context passed to HandshakeContext, 511 // if any, and is canceled when the handshake concludes. 512 func (c *CertificateRequestInfo) Context() context.Context { 513 return c.ctx 514 } 515 516 // RenegotiationSupport enumerates the different levels of support for TLS 517 // renegotiation. TLS renegotiation is the act of performing subsequent 518 // handshakes on a connection after the first. This significantly complicates 519 // the state machine and has been the source of numerous, subtle security 520 // issues. Initiating a renegotiation is not supported, but support for 521 // accepting renegotiation requests may be enabled. 522 // 523 // Even when enabled, the server may not change its identity between handshakes 524 // (i.e. the leaf certificate must be the same). Additionally, concurrent 525 // handshake and application data flow is not permitted so renegotiation can 526 // only be used with protocols that synchronise with the renegotiation, such as 527 // HTTPS. 528 // 529 // Renegotiation is not defined in TLS 1.3. 530 type RenegotiationSupport int 531 532 const ( 533 // RenegotiateNever disables renegotiation. 534 RenegotiateNever RenegotiationSupport = iota 535 536 // RenegotiateOnceAsClient allows a remote server to request 537 // renegotiation once per connection. 538 RenegotiateOnceAsClient 539 540 // RenegotiateFreelyAsClient allows a remote server to repeatedly 541 // request renegotiation. 542 RenegotiateFreelyAsClient 543 ) 544 545 // A Config structure is used to configure a TLS client or server. 546 // After one has been passed to a TLS function it must not be 547 // modified. A Config may be reused; the tls package will also not 548 // modify it. 549 type Config struct { 550 // Rand provides the source of entropy for nonces and RSA blinding. 551 // If Rand is nil, TLS uses the cryptographic random reader in package 552 // crypto/rand. 553 // The Reader must be safe for use by multiple goroutines. 554 Rand io.Reader 555 556 // Time returns the current time as the number of seconds since the epoch. 557 // If Time is nil, TLS uses time.Now. 558 Time func() time.Time 559 560 // Certificates contains one or more certificate chains to present to the 561 // other side of the connection. The first certificate compatible with the 562 // peer's requirements is selected automatically. 563 // 564 // Server configurations must set one of Certificates, GetCertificate or 565 // GetConfigForClient. Clients doing client-authentication may set either 566 // Certificates or GetClientCertificate. 567 // 568 // Note: if there are multiple Certificates, and they don't have the 569 // optional field Leaf set, certificate selection will incur a significant 570 // per-handshake performance cost. 571 Certificates []Certificate 572 573 // NameToCertificate maps from a certificate name to an element of 574 // Certificates. Note that a certificate name can be of the form 575 // '*.example.com' and so doesn't have to be a domain name as such. 576 // 577 // Deprecated: NameToCertificate only allows associating a single 578 // certificate with a given name. Leave this field nil to let the library 579 // select the first compatible chain from Certificates. 580 NameToCertificate map[string]*Certificate 581 582 // GetCertificate returns a Certificate based on the given 583 // ClientHelloInfo. It will only be called if the client supplies SNI 584 // information or if Certificates is empty. 585 // 586 // If GetCertificate is nil or returns nil, then the certificate is 587 // retrieved from NameToCertificate. If NameToCertificate is nil, the 588 // best element of Certificates will be used. 589 // 590 // Once a Certificate is returned it should not be modified. 591 GetCertificate func(*ClientHelloInfo) (*Certificate, error) 592 593 // GetClientCertificate, if not nil, is called when a server requests a 594 // certificate from a client. If set, the contents of Certificates will 595 // be ignored. 596 // 597 // If GetClientCertificate returns an error, the handshake will be 598 // aborted and that error will be returned. Otherwise 599 // GetClientCertificate must return a non-nil Certificate. If 600 // Certificate.Certificate is empty then no certificate will be sent to 601 // the server. If this is unacceptable to the server then it may abort 602 // the handshake. 603 // 604 // GetClientCertificate may be called multiple times for the same 605 // connection if renegotiation occurs or if TLS 1.3 is in use. 606 // 607 // Once a Certificate is returned it should not be modified. 608 GetClientCertificate func(*CertificateRequestInfo) (*Certificate, error) 609 610 // GetConfigForClient, if not nil, is called after a ClientHello is 611 // received from a client. It may return a non-nil Config in order to 612 // change the Config that will be used to handle this connection. If 613 // the returned Config is nil, the original Config will be used. The 614 // Config returned by this callback may not be subsequently modified. 615 // 616 // If GetConfigForClient is nil, the Config passed to Server() will be 617 // used for all connections. 618 // 619 // If SessionTicketKey is explicitly set on the returned Config, or if 620 // SetSessionTicketKeys is called on the returned Config, those keys will 621 // be used. Otherwise, the original Config keys will be used (and possibly 622 // rotated if they are automatically managed). WARNING: this allows session 623 // resumtion of connections originally established with the parent (or a 624 // sibling) Config, which may bypass the [Config.VerifyPeerCertificate] 625 // value of the returned Config. 626 GetConfigForClient func(*ClientHelloInfo) (*Config, error) 627 628 // VerifyPeerCertificate, if not nil, is called after normal 629 // certificate verification by either a TLS client or server. It 630 // receives the raw ASN.1 certificates provided by the peer and also 631 // any verified chains that normal processing found. If it returns a 632 // non-nil error, the handshake is aborted and that error results. 633 // 634 // If normal verification fails then the handshake will abort before 635 // considering this callback. If normal verification is disabled (on the 636 // client when InsecureSkipVerify is set, or on a server when ClientAuth is 637 // RequestClientCert or RequireAnyClientCert), then this callback will be 638 // considered but the verifiedChains argument will always be nil. When 639 // ClientAuth is NoClientCert, this callback is not called on the server. 640 // rawCerts may be empty on the server if ClientAuth is RequestClientCert or 641 // VerifyClientCertIfGiven. 642 // 643 // This callback is not invoked on resumed connections. WARNING: this 644 // includes connections resumed across Configs returned by [Config.Clone] or 645 // [Config.GetConfigForClient] and their parents. If that is not intended, 646 // use [Config.VerifyConnection] instead, or set [Config.SessionTicketsDisabled]. 647 // 648 // verifiedChains and its contents should not be modified. 649 VerifyPeerCertificate func(rawCerts [][]byte, verifiedChains [][]*x509.Certificate) error 650 651 // VerifyConnection, if not nil, is called after normal certificate 652 // verification and after VerifyPeerCertificate by either a TLS client 653 // or server. If it returns a non-nil error, the handshake is aborted 654 // and that error results. 655 // 656 // If normal verification fails then the handshake will abort before 657 // considering this callback. This callback will run for all connections, 658 // including resumptions, regardless of InsecureSkipVerify or ClientAuth 659 // settings. 660 VerifyConnection func(ConnectionState) error 661 662 // RootCAs defines the set of root certificate authorities 663 // that clients use when verifying server certificates. 664 // If RootCAs is nil, TLS uses the host's root CA set. 665 RootCAs *x509.CertPool 666 667 // NextProtos is a list of supported application level protocols, in 668 // order of preference. If both peers support ALPN, the selected 669 // protocol will be one from this list, and the connection will fail 670 // if there is no mutually supported protocol. If NextProtos is empty 671 // or the peer doesn't support ALPN, the connection will succeed and 672 // ConnectionState.NegotiatedProtocol will be empty. 673 NextProtos []string 674 675 // ServerName is used to verify the hostname on the returned 676 // certificates unless InsecureSkipVerify is given. It is also included 677 // in the client's handshake to support virtual hosting unless it is 678 // an IP address. 679 ServerName string 680 681 // ClientAuth determines the server's policy for 682 // TLS Client Authentication. The default is NoClientCert. 683 ClientAuth ClientAuthType 684 685 // ClientCAs defines the set of root certificate authorities 686 // that servers use if required to verify a client certificate 687 // by the policy in ClientAuth. 688 ClientCAs *x509.CertPool 689 690 // InsecureSkipVerify controls whether a client verifies the server's 691 // certificate chain and host name. If InsecureSkipVerify is true, crypto/tls 692 // accepts any certificate presented by the server and any host name in that 693 // certificate. In this mode, TLS is susceptible to machine-in-the-middle 694 // attacks unless custom verification is used. This should be used only for 695 // testing or in combination with VerifyConnection or VerifyPeerCertificate. 696 InsecureSkipVerify bool 697 698 // CipherSuites is a list of enabled TLS 1.0–1.2 cipher suites. The order of 699 // the list is ignored. Note that TLS 1.3 ciphersuites are not configurable. 700 // 701 // If CipherSuites is nil, a safe default list is used. The default cipher 702 // suites might change over time. In Go 1.22 RSA key exchange based cipher 703 // suites were removed from the default list, but can be re-added with the 704 // GODEBUG setting tlsrsakex=1. In Go 1.23 3DES cipher suites were removed 705 // from the default list, but can be re-added with the GODEBUG setting 706 // tls3des=1. 707 CipherSuites []uint16 708 709 // PreferServerCipherSuites is a legacy field and has no effect. 710 // 711 // It used to control whether the server would follow the client's or the 712 // server's preference. Servers now select the best mutually supported 713 // cipher suite based on logic that takes into account inferred client 714 // hardware, server hardware, and security. 715 // 716 // Deprecated: PreferServerCipherSuites is ignored. 717 PreferServerCipherSuites bool 718 719 // SessionTicketsDisabled may be set to true to disable session ticket and 720 // PSK (resumption) support. Note that on clients, session ticket support is 721 // also disabled if ClientSessionCache is nil. 722 SessionTicketsDisabled bool 723 724 // SessionTicketKey is used by TLS servers to provide session resumption. 725 // See RFC 5077 and the PSK mode of RFC 8446. If zero, it will be filled 726 // with random data before the first server handshake. 727 // 728 // Deprecated: if this field is left at zero, session ticket keys will be 729 // automatically rotated every day and dropped after seven days. For 730 // customizing the rotation schedule or synchronizing servers that are 731 // terminating connections for the same host, use SetSessionTicketKeys. 732 SessionTicketKey [32]byte 733 734 // ClientSessionCache is a cache of ClientSessionState entries for TLS 735 // session resumption. It is only used by clients. 736 ClientSessionCache ClientSessionCache 737 738 // UnwrapSession is called on the server to turn a ticket/identity 739 // previously produced by [WrapSession] into a usable session. 740 // 741 // UnwrapSession will usually either decrypt a session state in the ticket 742 // (for example with [Config.EncryptTicket]), or use the ticket as a handle 743 // to recover a previously stored state. It must use [ParseSessionState] to 744 // deserialize the session state. 745 // 746 // If UnwrapSession returns an error, the connection is terminated. If it 747 // returns (nil, nil), the session is ignored. crypto/tls may still choose 748 // not to resume the returned session. 749 UnwrapSession func(identity []byte, cs ConnectionState) (*SessionState, error) 750 751 // WrapSession is called on the server to produce a session ticket/identity. 752 // 753 // WrapSession must serialize the session state with [SessionState.Bytes]. 754 // It may then encrypt the serialized state (for example with 755 // [Config.DecryptTicket]) and use it as the ticket, or store the state and 756 // return a handle for it. 757 // 758 // If WrapSession returns an error, the connection is terminated. 759 // 760 // Warning: the return value will be exposed on the wire and to clients in 761 // plaintext. The application is in charge of encrypting and authenticating 762 // it (and rotating keys) or returning high-entropy identifiers. Failing to 763 // do so correctly can compromise current, previous, and future connections 764 // depending on the protocol version. 765 WrapSession func(ConnectionState, *SessionState) ([]byte, error) 766 767 // MinVersion contains the minimum TLS version that is acceptable. 768 // 769 // By default, TLS 1.2 is currently used as the minimum. TLS 1.0 is the 770 // minimum supported by this package. 771 // 772 // The server-side default can be reverted to TLS 1.0 by including the value 773 // "tls10server=1" in the GODEBUG environment variable. 774 MinVersion uint16 775 776 // MaxVersion contains the maximum TLS version that is acceptable. 777 // 778 // By default, the maximum version supported by this package is used, 779 // which is currently TLS 1.3. 780 MaxVersion uint16 781 782 // CurvePreferences contains a set of supported key exchange mechanisms. 783 // The name refers to elliptic curves for legacy reasons, see [CurveID]. 784 // The order of the list is ignored, and key exchange mechanisms are chosen 785 // from this list using an internal preference order. If empty, the default 786 // will be used. 787 // 788 // From Go 1.24, the default includes the [X25519MLKEM768] hybrid 789 // post-quantum key exchange. To disable it, set CurvePreferences explicitly 790 // or use the GODEBUG=tlsmlkem=0 environment variable. 791 CurvePreferences []CurveID 792 793 // DynamicRecordSizingDisabled disables adaptive sizing of TLS records. 794 // When true, the largest possible TLS record size is always used. When 795 // false, the size of TLS records may be adjusted in an attempt to 796 // improve latency. 797 DynamicRecordSizingDisabled bool 798 799 // Renegotiation controls what types of renegotiation are supported. 800 // The default, none, is correct for the vast majority of applications. 801 Renegotiation RenegotiationSupport 802 803 // KeyLogWriter optionally specifies a destination for TLS master secrets 804 // in NSS key log format that can be used to allow external programs 805 // such as Wireshark to decrypt TLS connections. 806 // See https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Key_Log_Format. 807 // Use of KeyLogWriter compromises security and should only be 808 // used for debugging. 809 KeyLogWriter io.Writer 810 811 // EncryptedClientHelloConfigList is a serialized ECHConfigList. If 812 // provided, clients will attempt to connect to servers using Encrypted 813 // Client Hello (ECH) using one of the provided ECHConfigs. 814 // 815 // Servers do not use this field. In order to configure ECH for servers, see 816 // the EncryptedClientHelloKeys field. 817 // 818 // If the list contains no valid ECH configs, the handshake will fail 819 // and return an error. 820 // 821 // If EncryptedClientHelloConfigList is set, MinVersion, if set, must 822 // be VersionTLS13. 823 // 824 // When EncryptedClientHelloConfigList is set, the handshake will only 825 // succeed if ECH is successfully negotiated. If the server rejects ECH, 826 // an ECHRejectionError error will be returned, which may contain a new 827 // ECHConfigList that the server suggests using. 828 // 829 // How this field is parsed may change in future Go versions, if the 830 // encoding described in the final Encrypted Client Hello RFC changes. 831 EncryptedClientHelloConfigList []byte 832 833 // EncryptedClientHelloRejectionVerify, if not nil, is called when ECH is 834 // rejected by the remote server, in order to verify the ECH provider 835 // certificate in the outer ClientHello. If it returns a non-nil error, the 836 // handshake is aborted and that error results. 837 // 838 // On the server side this field is not used. 839 // 840 // Unlike VerifyPeerCertificate and VerifyConnection, normal certificate 841 // verification will not be performed before calling 842 // EncryptedClientHelloRejectionVerify. 843 // 844 // If EncryptedClientHelloRejectionVerify is nil and ECH is rejected, the 845 // roots in RootCAs will be used to verify the ECH providers public 846 // certificate. VerifyPeerCertificate and VerifyConnection are not called 847 // when ECH is rejected, even if set, and InsecureSkipVerify is ignored. 848 EncryptedClientHelloRejectionVerify func(ConnectionState) error 849 850 // GetEncryptedClientHelloKeys, if not nil, is called when by a server when 851 // a client attempts ECH. 852 // 853 // If GetEncryptedClientHelloKeys is not nil, [EncryptedClientHelloKeys] is 854 // ignored. 855 // 856 // If GetEncryptedClientHelloKeys returns an error, the handshake will be 857 // aborted and the error will be returned. Otherwise, 858 // GetEncryptedClientHelloKeys must return a non-nil slice of 859 // [EncryptedClientHelloKey] that represents the acceptable ECH keys. 860 // 861 // For further details, see [EncryptedClientHelloKeys]. 862 GetEncryptedClientHelloKeys func(*ClientHelloInfo) ([]EncryptedClientHelloKey, error) 863 864 // EncryptedClientHelloKeys are the ECH keys to use when a client 865 // attempts ECH. 866 // 867 // If EncryptedClientHelloKeys is set, MinVersion, if set, must be 868 // VersionTLS13. 869 // 870 // If a client attempts ECH, but it is rejected by the server, the server 871 // will send a list of configs to retry based on the set of 872 // EncryptedClientHelloKeys which have the SendAsRetry field set. 873 // 874 // If GetEncryptedClientHelloKeys is non-nil, EncryptedClientHelloKeys is 875 // ignored. 876 // 877 // On the client side, this field is ignored. In order to configure ECH for 878 // clients, see the EncryptedClientHelloConfigList field. 879 EncryptedClientHelloKeys []EncryptedClientHelloKey 880 881 // mutex protects sessionTicketKeys and autoSessionTicketKeys. 882 mutex sync.RWMutex 883 // sessionTicketKeys contains zero or more ticket keys. If set, it means 884 // the keys were set with SessionTicketKey or SetSessionTicketKeys. The 885 // first key is used for new tickets and any subsequent keys can be used to 886 // decrypt old tickets. The slice contents are not protected by the mutex 887 // and are immutable. 888 sessionTicketKeys []ticketKey 889 // autoSessionTicketKeys is like sessionTicketKeys but is owned by the 890 // auto-rotation logic. See Config.ticketKeys. 891 autoSessionTicketKeys []ticketKey 892 } 893 894 // EncryptedClientHelloKey holds a private key that is associated 895 // with a specific ECH config known to a client. 896 type EncryptedClientHelloKey struct { 897 // Config should be a marshalled ECHConfig associated with PrivateKey. This 898 // must match the config provided to clients byte-for-byte. The config 899 // should only specify the DHKEM(X25519, HKDF-SHA256) KEM ID (0x0020), the 900 // HKDF-SHA256 KDF ID (0x0001), and a subset of the following AEAD IDs: 901 // AES-128-GCM (0x0001), AES-256-GCM (0x0002), ChaCha20Poly1305 (0x0003). 902 Config []byte 903 // PrivateKey should be a marshalled private key. Currently, we expect 904 // this to be the output of [ecdh.PrivateKey.Bytes]. 905 PrivateKey []byte 906 // SendAsRetry indicates if Config should be sent as part of the list of 907 // retry configs when ECH is requested by the client but rejected by the 908 // server. 909 SendAsRetry bool 910 } 911 912 const ( 913 // ticketKeyLifetime is how long a ticket key remains valid and can be used to 914 // resume a client connection. 915 ticketKeyLifetime = 7 * 24 * time.Hour // 7 days 916 917 // ticketKeyRotation is how often the server should rotate the session ticket key 918 // that is used for new tickets. 919 ticketKeyRotation = 24 * time.Hour 920 ) 921 922 // ticketKey is the internal representation of a session ticket key. 923 type ticketKey struct { 924 aesKey [16]byte 925 hmacKey [16]byte 926 // created is the time at which this ticket key was created. See Config.ticketKeys. 927 created time.Time 928 } 929 930 // ticketKeyFromBytes converts from the external representation of a session 931 // ticket key to a ticketKey. Externally, session ticket keys are 32 random 932 // bytes and this function expands that into sufficient name and key material. 933 func (c *Config) ticketKeyFromBytes(b [32]byte) (key ticketKey) { 934 hashed := sha512.Sum512(b[:]) 935 // The first 16 bytes of the hash used to be exposed on the wire as a ticket 936 // prefix. They MUST NOT be used as a secret. In the future, it would make 937 // sense to use a proper KDF here, like HKDF with a fixed salt. 938 const legacyTicketKeyNameLen = 16 939 copy(key.aesKey[:], hashed[legacyTicketKeyNameLen:]) 940 copy(key.hmacKey[:], hashed[legacyTicketKeyNameLen+len(key.aesKey):]) 941 key.created = c.time() 942 return key 943 } 944 945 // maxSessionTicketLifetime is the maximum allowed lifetime of a TLS 1.3 session 946 // ticket, and the lifetime we set for all tickets we send. 947 const maxSessionTicketLifetime = 7 * 24 * time.Hour 948 949 // Clone returns a shallow clone of c or nil if c is nil. It is safe to clone a 950 // [Config] that is being used concurrently by a TLS client or server. 951 // 952 // The returned Config can share session ticket keys with the original Config, 953 // which means connections could be resumed across the two Configs. WARNING: 954 // [Config.VerifyPeerCertificate] does not get called on resumed connections, 955 // including connections that were originally established on the parent Config. 956 // If that is not intended, use [Config.VerifyConnection] instead, or set 957 // [Config.SessionTicketsDisabled]. 958 func (c *Config) Clone() *Config { 959 if c == nil { 960 return nil 961 } 962 c.mutex.RLock() 963 defer c.mutex.RUnlock() 964 return &Config{ 965 Rand: c.Rand, 966 Time: c.Time, 967 Certificates: c.Certificates, 968 NameToCertificate: c.NameToCertificate, 969 GetCertificate: c.GetCertificate, 970 GetClientCertificate: c.GetClientCertificate, 971 GetConfigForClient: c.GetConfigForClient, 972 GetEncryptedClientHelloKeys: c.GetEncryptedClientHelloKeys, 973 VerifyPeerCertificate: c.VerifyPeerCertificate, 974 VerifyConnection: c.VerifyConnection, 975 RootCAs: c.RootCAs, 976 NextProtos: c.NextProtos, 977 ServerName: c.ServerName, 978 ClientAuth: c.ClientAuth, 979 ClientCAs: c.ClientCAs, 980 InsecureSkipVerify: c.InsecureSkipVerify, 981 CipherSuites: c.CipherSuites, 982 PreferServerCipherSuites: c.PreferServerCipherSuites, 983 SessionTicketsDisabled: c.SessionTicketsDisabled, 984 SessionTicketKey: c.SessionTicketKey, 985 ClientSessionCache: c.ClientSessionCache, 986 UnwrapSession: c.UnwrapSession, 987 WrapSession: c.WrapSession, 988 MinVersion: c.MinVersion, 989 MaxVersion: c.MaxVersion, 990 CurvePreferences: c.CurvePreferences, 991 DynamicRecordSizingDisabled: c.DynamicRecordSizingDisabled, 992 Renegotiation: c.Renegotiation, 993 KeyLogWriter: c.KeyLogWriter, 994 EncryptedClientHelloConfigList: c.EncryptedClientHelloConfigList, 995 EncryptedClientHelloRejectionVerify: c.EncryptedClientHelloRejectionVerify, 996 EncryptedClientHelloKeys: c.EncryptedClientHelloKeys, 997 sessionTicketKeys: c.sessionTicketKeys, 998 autoSessionTicketKeys: c.autoSessionTicketKeys, 999 } 1000 } 1001 1002 // deprecatedSessionTicketKey is set as the prefix of SessionTicketKey if it was 1003 // randomized for backwards compatibility but is not in use. 1004 var deprecatedSessionTicketKey = []byte("DEPRECATED") 1005 1006 // initLegacySessionTicketKeyRLocked ensures the legacy SessionTicketKey field is 1007 // randomized if empty, and that sessionTicketKeys is populated from it otherwise. 1008 func (c *Config) initLegacySessionTicketKeyRLocked() { 1009 // Don't write if SessionTicketKey is already defined as our deprecated string, 1010 // or if it is defined by the user but sessionTicketKeys is already set. 1011 if c.SessionTicketKey != [32]byte{} && 1012 (bytes.HasPrefix(c.SessionTicketKey[:], deprecatedSessionTicketKey) || len(c.sessionTicketKeys) > 0) { 1013 return 1014 } 1015 1016 // We need to write some data, so get an exclusive lock and re-check any conditions. 1017 c.mutex.RUnlock() 1018 defer c.mutex.RLock() 1019 c.mutex.Lock() 1020 defer c.mutex.Unlock() 1021 if c.SessionTicketKey == [32]byte{} { 1022 if _, err := io.ReadFull(c.rand(), c.SessionTicketKey[:]); err != nil { 1023 panic(fmt.Sprintf("tls: unable to generate random session ticket key: %v", err)) 1024 } 1025 // Write the deprecated prefix at the beginning so we know we created 1026 // it. This key with the DEPRECATED prefix isn't used as an actual 1027 // session ticket key, and is only randomized in case the application 1028 // reuses it for some reason. 1029 copy(c.SessionTicketKey[:], deprecatedSessionTicketKey) 1030 } else if !bytes.HasPrefix(c.SessionTicketKey[:], deprecatedSessionTicketKey) && len(c.sessionTicketKeys) == 0 { 1031 c.sessionTicketKeys = []ticketKey{c.ticketKeyFromBytes(c.SessionTicketKey)} 1032 } 1033 1034 } 1035 1036 // ticketKeys returns the ticketKeys for this connection. 1037 // If configForClient has explicitly set keys, those will 1038 // be returned. Otherwise, the keys on c will be used and 1039 // may be rotated if auto-managed. 1040 // During rotation, any expired session ticket keys are deleted from 1041 // c.sessionTicketKeys. If the session ticket key that is currently 1042 // encrypting tickets (ie. the first ticketKey in c.sessionTicketKeys) 1043 // is not fresh, then a new session ticket key will be 1044 // created and prepended to c.sessionTicketKeys. 1045 func (c *Config) ticketKeys(configForClient *Config) []ticketKey { 1046 // If the ConfigForClient callback returned a Config with explicitly set 1047 // keys, use those, otherwise just use the original Config. 1048 if configForClient != nil { 1049 configForClient.mutex.RLock() 1050 if configForClient.SessionTicketsDisabled { 1051 configForClient.mutex.RUnlock() 1052 return nil 1053 } 1054 configForClient.initLegacySessionTicketKeyRLocked() 1055 if len(configForClient.sessionTicketKeys) != 0 { 1056 ret := configForClient.sessionTicketKeys 1057 configForClient.mutex.RUnlock() 1058 return ret 1059 } 1060 configForClient.mutex.RUnlock() 1061 } 1062 1063 c.mutex.RLock() 1064 defer c.mutex.RUnlock() 1065 if c.SessionTicketsDisabled { 1066 return nil 1067 } 1068 c.initLegacySessionTicketKeyRLocked() 1069 if len(c.sessionTicketKeys) != 0 { 1070 return c.sessionTicketKeys 1071 } 1072 // Fast path for the common case where the key is fresh enough. 1073 if len(c.autoSessionTicketKeys) > 0 && c.time().Sub(c.autoSessionTicketKeys[0].created) < ticketKeyRotation { 1074 return c.autoSessionTicketKeys 1075 } 1076 1077 // autoSessionTicketKeys are managed by auto-rotation. 1078 c.mutex.RUnlock() 1079 defer c.mutex.RLock() 1080 c.mutex.Lock() 1081 defer c.mutex.Unlock() 1082 // Re-check the condition in case it changed since obtaining the new lock. 1083 if len(c.autoSessionTicketKeys) == 0 || c.time().Sub(c.autoSessionTicketKeys[0].created) >= ticketKeyRotation { 1084 var newKey [32]byte 1085 if _, err := io.ReadFull(c.rand(), newKey[:]); err != nil { 1086 panic(fmt.Sprintf("unable to generate random session ticket key: %v", err)) 1087 } 1088 valid := make([]ticketKey, 0, len(c.autoSessionTicketKeys)+1) 1089 valid = append(valid, c.ticketKeyFromBytes(newKey)) 1090 for _, k := range c.autoSessionTicketKeys { 1091 // While rotating the current key, also remove any expired ones. 1092 if c.time().Sub(k.created) < ticketKeyLifetime { 1093 valid = append(valid, k) 1094 } 1095 } 1096 c.autoSessionTicketKeys = valid 1097 } 1098 return c.autoSessionTicketKeys 1099 } 1100 1101 // SetSessionTicketKeys updates the session ticket keys for a server. 1102 // 1103 // The first key will be used when creating new tickets, while all keys can be 1104 // used for decrypting tickets. It is safe to call this function while the 1105 // server is running in order to rotate the session ticket keys. The function 1106 // will panic if keys is empty. 1107 // 1108 // Calling this function will turn off automatic session ticket key rotation. 1109 // 1110 // If multiple servers are terminating connections for the same host they should 1111 // all have the same session ticket keys. If the session ticket keys leaks, 1112 // previously recorded and future TLS connections using those keys might be 1113 // compromised. 1114 func (c *Config) SetSessionTicketKeys(keys [][32]byte) { 1115 if len(keys) == 0 { 1116 panic("tls: keys must have at least one key") 1117 } 1118 1119 newKeys := make([]ticketKey, len(keys)) 1120 for i, bytes := range keys { 1121 newKeys[i] = c.ticketKeyFromBytes(bytes) 1122 } 1123 1124 c.mutex.Lock() 1125 c.sessionTicketKeys = newKeys 1126 c.mutex.Unlock() 1127 } 1128 1129 func (c *Config) rand() io.Reader { 1130 r := c.Rand 1131 if r == nil { 1132 return rand.Reader 1133 } 1134 return r 1135 } 1136 1137 func (c *Config) time() time.Time { 1138 t := c.Time 1139 if t == nil { 1140 t = time.Now 1141 } 1142 return t() 1143 } 1144 1145 func (c *Config) cipherSuites(aesGCMPreferred bool) []uint16 { 1146 var cipherSuites []uint16 1147 if c.CipherSuites == nil { 1148 cipherSuites = defaultCipherSuites(aesGCMPreferred) 1149 } else { 1150 cipherSuites = supportedCipherSuites(aesGCMPreferred) 1151 cipherSuites = slices.DeleteFunc(cipherSuites, func(id uint16) bool { 1152 return !slices.Contains(c.CipherSuites, id) 1153 }) 1154 } 1155 if fips140tls.Required() { 1156 cipherSuites = slices.DeleteFunc(cipherSuites, func(id uint16) bool { 1157 return !slices.Contains(allowedCipherSuitesFIPS, id) 1158 }) 1159 } 1160 return cipherSuites 1161 } 1162 1163 // supportedCipherSuites returns the supported TLS 1.0–1.2 cipher suites in an 1164 // undefined order. For preference ordering, use [Config.cipherSuites]. 1165 func (c *Config) supportedCipherSuites() []uint16 { 1166 return c.cipherSuites(false) 1167 } 1168 1169 var supportedVersions = []uint16{ 1170 VersionTLS13, 1171 VersionTLS12, 1172 VersionTLS11, 1173 VersionTLS10, 1174 } 1175 1176 // roleClient and roleServer are meant to call supportedVersions and parents 1177 // with more readability at the callsite. 1178 const roleClient = true 1179 const roleServer = false 1180 1181 var tls10server = godebug.New("tls10server") 1182 1183 // supportedVersions returns the list of supported TLS versions, sorted from 1184 // highest to lowest (and hence also in preference order). 1185 func (c *Config) supportedVersions(isClient bool) []uint16 { 1186 versions := make([]uint16, 0, len(supportedVersions)) 1187 for _, v := range supportedVersions { 1188 if fips140tls.Required() && !slices.Contains(allowedSupportedVersionsFIPS, v) { 1189 continue 1190 } 1191 if (c == nil || c.MinVersion == 0) && v < VersionTLS12 { 1192 if isClient || tls10server.Value() != "1" { 1193 continue 1194 } 1195 } 1196 if isClient && c.EncryptedClientHelloConfigList != nil && v < VersionTLS13 { 1197 continue 1198 } 1199 if c != nil && c.MinVersion != 0 && v < c.MinVersion { 1200 continue 1201 } 1202 if c != nil && c.MaxVersion != 0 && v > c.MaxVersion { 1203 continue 1204 } 1205 versions = append(versions, v) 1206 } 1207 return versions 1208 } 1209 1210 func (c *Config) maxSupportedVersion(isClient bool) uint16 { 1211 supportedVersions := c.supportedVersions(isClient) 1212 if len(supportedVersions) == 0 { 1213 return 0 1214 } 1215 return supportedVersions[0] 1216 } 1217 1218 // supportedVersionsFromMax returns a list of supported versions derived from a 1219 // legacy maximum version value. Note that only versions supported by this 1220 // library are returned. Any newer peer will use supportedVersions anyway. 1221 func supportedVersionsFromMax(maxVersion uint16) []uint16 { 1222 versions := make([]uint16, 0, len(supportedVersions)) 1223 for _, v := range supportedVersions { 1224 if v > maxVersion { 1225 continue 1226 } 1227 versions = append(versions, v) 1228 } 1229 return versions 1230 } 1231 1232 func (c *Config) curvePreferences(version uint16) []CurveID { 1233 curvePreferences := defaultCurvePreferences() 1234 if fips140tls.Required() { 1235 curvePreferences = slices.DeleteFunc(curvePreferences, func(x CurveID) bool { 1236 return !slices.Contains(allowedCurvePreferencesFIPS, x) 1237 }) 1238 } 1239 if c != nil && len(c.CurvePreferences) != 0 { 1240 curvePreferences = slices.DeleteFunc(curvePreferences, func(x CurveID) bool { 1241 return !slices.Contains(c.CurvePreferences, x) 1242 }) 1243 } 1244 if version < VersionTLS13 { 1245 curvePreferences = slices.DeleteFunc(curvePreferences, isTLS13OnlyKeyExchange) 1246 } 1247 return curvePreferences 1248 } 1249 1250 func (c *Config) supportsCurve(version uint16, curve CurveID) bool { 1251 return slices.Contains(c.curvePreferences(version), curve) 1252 } 1253 1254 // mutualVersion returns the protocol version to use given the advertised 1255 // versions of the peer. The highest supported version is preferred. 1256 func (c *Config) mutualVersion(isClient bool, peerVersions []uint16) (uint16, bool) { 1257 supportedVersions := c.supportedVersions(isClient) 1258 for _, v := range supportedVersions { 1259 if slices.Contains(peerVersions, v) { 1260 return v, true 1261 } 1262 } 1263 return 0, false 1264 } 1265 1266 // errNoCertificates should be an internal detail, 1267 // but widely used packages access it using linkname. 1268 // Notable members of the hall of shame include: 1269 // - github.com/xtls/xray-core 1270 // 1271 // Do not remove or change the type signature. 1272 // See go.dev/issue/67401. 1273 // 1274 //go:linkname errNoCertificates 1275 var errNoCertificates = errors.New("tls: no certificates configured") 1276 1277 // getCertificate returns the best certificate for the given ClientHelloInfo, 1278 // defaulting to the first element of c.Certificates. 1279 func (c *Config) getCertificate(clientHello *ClientHelloInfo) (*Certificate, error) { 1280 if c.GetCertificate != nil && 1281 (len(c.Certificates) == 0 || len(clientHello.ServerName) > 0) { 1282 cert, err := c.GetCertificate(clientHello) 1283 if cert != nil || err != nil { 1284 return cert, err 1285 } 1286 } 1287 1288 if len(c.Certificates) == 0 { 1289 return nil, errNoCertificates 1290 } 1291 1292 if len(c.Certificates) == 1 { 1293 // There's only one choice, so no point doing any work. 1294 return &c.Certificates[0], nil 1295 } 1296 1297 if c.NameToCertificate != nil { 1298 name := strings.ToLower(clientHello.ServerName) 1299 if cert, ok := c.NameToCertificate[name]; ok { 1300 return cert, nil 1301 } 1302 if len(name) > 0 { 1303 labels := strings.Split(name, ".") 1304 labels[0] = "*" 1305 wildcardName := strings.Join(labels, ".") 1306 if cert, ok := c.NameToCertificate[wildcardName]; ok { 1307 return cert, nil 1308 } 1309 } 1310 } 1311 1312 for _, cert := range c.Certificates { 1313 if err := clientHello.SupportsCertificate(&cert); err == nil { 1314 return &cert, nil 1315 } 1316 } 1317 1318 // If nothing matches, return the first certificate. 1319 return &c.Certificates[0], nil 1320 } 1321 1322 // SupportsCertificate returns nil if the provided certificate is supported by 1323 // the client that sent the ClientHello. Otherwise, it returns an error 1324 // describing the reason for the incompatibility. 1325 // 1326 // If this [ClientHelloInfo] was passed to a GetConfigForClient or GetCertificate 1327 // callback, this method will take into account the associated [Config]. Note that 1328 // if GetConfigForClient returns a different [Config], the change can't be 1329 // accounted for by this method. 1330 // 1331 // This function will call x509.ParseCertificate unless c.Leaf is set, which can 1332 // incur a significant performance cost. 1333 func (chi *ClientHelloInfo) SupportsCertificate(c *Certificate) error { 1334 // Note we don't currently support certificate_authorities nor 1335 // signature_algorithms_cert, and don't check the algorithms of the 1336 // signatures on the chain (which anyway are a SHOULD, see RFC 8446, 1337 // Section 4.4.2.2). 1338 1339 config := chi.config 1340 if config == nil { 1341 config = &Config{} 1342 } 1343 vers, ok := config.mutualVersion(roleServer, chi.SupportedVersions) 1344 if !ok { 1345 return errors.New("no mutually supported protocol versions") 1346 } 1347 1348 // If the client specified the name they are trying to connect to, the 1349 // certificate needs to be valid for it. 1350 if chi.ServerName != "" { 1351 x509Cert, err := c.leaf() 1352 if err != nil { 1353 return fmt.Errorf("failed to parse certificate: %w", err) 1354 } 1355 if err := x509Cert.VerifyHostname(chi.ServerName); err != nil { 1356 return fmt.Errorf("certificate is not valid for requested server name: %w", err) 1357 } 1358 } 1359 1360 // supportsRSAFallback returns nil if the certificate and connection support 1361 // the static RSA key exchange, and unsupported otherwise. The logic for 1362 // supporting static RSA is completely disjoint from the logic for 1363 // supporting signed key exchanges, so we just check it as a fallback. 1364 supportsRSAFallback := func(unsupported error) error { 1365 // TLS 1.3 dropped support for the static RSA key exchange. 1366 if vers == VersionTLS13 { 1367 return unsupported 1368 } 1369 // The static RSA key exchange works by decrypting a challenge with the 1370 // RSA private key, not by signing, so check the PrivateKey implements 1371 // crypto.Decrypter, like *rsa.PrivateKey does. 1372 if priv, ok := c.PrivateKey.(crypto.Decrypter); ok { 1373 if _, ok := priv.Public().(*rsa.PublicKey); !ok { 1374 return unsupported 1375 } 1376 } else { 1377 return unsupported 1378 } 1379 // Finally, there needs to be a mutual cipher suite that uses the static 1380 // RSA key exchange instead of ECDHE. 1381 rsaCipherSuite := selectCipherSuite(chi.CipherSuites, config.supportedCipherSuites(), func(c *cipherSuite) bool { 1382 if c.flags&suiteECDHE != 0 { 1383 return false 1384 } 1385 if vers < VersionTLS12 && c.flags&suiteTLS12 != 0 { 1386 return false 1387 } 1388 return true 1389 }) 1390 if rsaCipherSuite == nil { 1391 return unsupported 1392 } 1393 return nil 1394 } 1395 1396 // If the client sent the signature_algorithms extension, ensure it supports 1397 // schemes we can use with this certificate and TLS version. 1398 if len(chi.SignatureSchemes) > 0 { 1399 if _, err := selectSignatureScheme(vers, c, chi.SignatureSchemes); err != nil { 1400 return supportsRSAFallback(err) 1401 } 1402 } 1403 1404 // In TLS 1.3 we are done because supported_groups is only relevant to the 1405 // ECDHE computation, point format negotiation is removed, cipher suites are 1406 // only relevant to the AEAD choice, and static RSA does not exist. 1407 if vers == VersionTLS13 { 1408 return nil 1409 } 1410 1411 // The only signed key exchange we support is ECDHE. 1412 ecdheSupported, err := supportsECDHE(config, vers, chi.SupportedCurves, chi.SupportedPoints) 1413 if err != nil { 1414 return err 1415 } 1416 if !ecdheSupported { 1417 return supportsRSAFallback(errors.New("client doesn't support ECDHE, can only use legacy RSA key exchange")) 1418 } 1419 1420 var ecdsaCipherSuite bool 1421 if priv, ok := c.PrivateKey.(crypto.Signer); ok { 1422 switch pub := priv.Public().(type) { 1423 case *ecdsa.PublicKey: 1424 var curve CurveID 1425 switch pub.Curve { 1426 case elliptic.P256(): 1427 curve = CurveP256 1428 case elliptic.P384(): 1429 curve = CurveP384 1430 case elliptic.P521(): 1431 curve = CurveP521 1432 default: 1433 return supportsRSAFallback(unsupportedCertificateError(c)) 1434 } 1435 var curveOk bool 1436 for _, c := range chi.SupportedCurves { 1437 if c == curve && config.supportsCurve(vers, c) { 1438 curveOk = true 1439 break 1440 } 1441 } 1442 if !curveOk { 1443 return errors.New("client doesn't support certificate curve") 1444 } 1445 ecdsaCipherSuite = true 1446 case ed25519.PublicKey: 1447 if vers < VersionTLS12 || len(chi.SignatureSchemes) == 0 { 1448 return errors.New("connection doesn't support Ed25519") 1449 } 1450 ecdsaCipherSuite = true 1451 case *rsa.PublicKey: 1452 default: 1453 return supportsRSAFallback(unsupportedCertificateError(c)) 1454 } 1455 } else { 1456 return supportsRSAFallback(unsupportedCertificateError(c)) 1457 } 1458 1459 // Make sure that there is a mutually supported cipher suite that works with 1460 // this certificate. Cipher suite selection will then apply the logic in 1461 // reverse to pick it. See also serverHandshakeState.cipherSuiteOk. 1462 cipherSuite := selectCipherSuite(chi.CipherSuites, config.supportedCipherSuites(), func(c *cipherSuite) bool { 1463 if c.flags&suiteECDHE == 0 { 1464 return false 1465 } 1466 if c.flags&suiteECSign != 0 { 1467 if !ecdsaCipherSuite { 1468 return false 1469 } 1470 } else { 1471 if ecdsaCipherSuite { 1472 return false 1473 } 1474 } 1475 if vers < VersionTLS12 && c.flags&suiteTLS12 != 0 { 1476 return false 1477 } 1478 return true 1479 }) 1480 if cipherSuite == nil { 1481 return supportsRSAFallback(errors.New("client doesn't support any cipher suites compatible with the certificate")) 1482 } 1483 1484 return nil 1485 } 1486 1487 // SupportsCertificate returns nil if the provided certificate is supported by 1488 // the server that sent the CertificateRequest. Otherwise, it returns an error 1489 // describing the reason for the incompatibility. 1490 func (cri *CertificateRequestInfo) SupportsCertificate(c *Certificate) error { 1491 if _, err := selectSignatureScheme(cri.Version, c, cri.SignatureSchemes); err != nil { 1492 return err 1493 } 1494 1495 if len(cri.AcceptableCAs) == 0 { 1496 return nil 1497 } 1498 1499 for j, cert := range c.Certificate { 1500 x509Cert := c.Leaf 1501 // Parse the certificate if this isn't the leaf node, or if 1502 // chain.Leaf was nil. 1503 if j != 0 || x509Cert == nil { 1504 var err error 1505 if x509Cert, err = x509.ParseCertificate(cert); err != nil { 1506 return fmt.Errorf("failed to parse certificate #%d in the chain: %w", j, err) 1507 } 1508 } 1509 1510 for _, ca := range cri.AcceptableCAs { 1511 if bytes.Equal(x509Cert.RawIssuer, ca) { 1512 return nil 1513 } 1514 } 1515 } 1516 return errors.New("chain is not signed by an acceptable CA") 1517 } 1518 1519 // BuildNameToCertificate parses c.Certificates and builds c.NameToCertificate 1520 // from the CommonName and SubjectAlternateName fields of each of the leaf 1521 // certificates. 1522 // 1523 // Deprecated: NameToCertificate only allows associating a single certificate 1524 // with a given name. Leave that field nil to let the library select the first 1525 // compatible chain from Certificates. 1526 func (c *Config) BuildNameToCertificate() { 1527 c.NameToCertificate = make(map[string]*Certificate) 1528 for i := range c.Certificates { 1529 cert := &c.Certificates[i] 1530 x509Cert, err := cert.leaf() 1531 if err != nil { 1532 continue 1533 } 1534 // If SANs are *not* present, some clients will consider the certificate 1535 // valid for the name in the Common Name. 1536 if x509Cert.Subject.CommonName != "" && len(x509Cert.DNSNames) == 0 { 1537 c.NameToCertificate[x509Cert.Subject.CommonName] = cert 1538 } 1539 for _, san := range x509Cert.DNSNames { 1540 c.NameToCertificate[san] = cert 1541 } 1542 } 1543 } 1544 1545 const ( 1546 keyLogLabelTLS12 = "CLIENT_RANDOM" 1547 keyLogLabelClientHandshake = "CLIENT_HANDSHAKE_TRAFFIC_SECRET" 1548 keyLogLabelServerHandshake = "SERVER_HANDSHAKE_TRAFFIC_SECRET" 1549 keyLogLabelClientTraffic = "CLIENT_TRAFFIC_SECRET_0" 1550 keyLogLabelServerTraffic = "SERVER_TRAFFIC_SECRET_0" 1551 ) 1552 1553 func (c *Config) writeKeyLog(label string, clientRandom, secret []byte) error { 1554 if c.KeyLogWriter == nil { 1555 return nil 1556 } 1557 1558 logLine := fmt.Appendf(nil, "%s %x %x\n", label, clientRandom, secret) 1559 1560 writerMutex.Lock() 1561 _, err := c.KeyLogWriter.Write(logLine) 1562 writerMutex.Unlock() 1563 1564 return err 1565 } 1566 1567 // writerMutex protects all KeyLogWriters globally. It is rarely enabled, 1568 // and is only for debugging, so a global mutex saves space. 1569 var writerMutex sync.Mutex 1570 1571 // A Certificate is a chain of one or more certificates, leaf first. 1572 type Certificate struct { 1573 Certificate [][]byte 1574 // PrivateKey contains the private key corresponding to the public key in 1575 // Leaf. This must implement crypto.Signer with an RSA, ECDSA or Ed25519 PublicKey. 1576 // For a server up to TLS 1.2, it can also implement crypto.Decrypter with 1577 // an RSA PublicKey. 1578 PrivateKey crypto.PrivateKey 1579 // SupportedSignatureAlgorithms is an optional list restricting what 1580 // signature algorithms the PrivateKey can be used for. 1581 SupportedSignatureAlgorithms []SignatureScheme 1582 // OCSPStaple contains an optional OCSP response which will be served 1583 // to clients that request it. 1584 OCSPStaple []byte 1585 // SignedCertificateTimestamps contains an optional list of Signed 1586 // Certificate Timestamps which will be served to clients that request it. 1587 SignedCertificateTimestamps [][]byte 1588 // Leaf is the parsed form of the leaf certificate, which may be initialized 1589 // using x509.ParseCertificate to reduce per-handshake processing. If nil, 1590 // the leaf certificate will be parsed as needed. 1591 Leaf *x509.Certificate 1592 } 1593 1594 // leaf returns the parsed leaf certificate, either from c.Leaf or by parsing 1595 // the corresponding c.Certificate[0]. 1596 func (c *Certificate) leaf() (*x509.Certificate, error) { 1597 if c.Leaf != nil { 1598 return c.Leaf, nil 1599 } 1600 return x509.ParseCertificate(c.Certificate[0]) 1601 } 1602 1603 type handshakeMessage interface { 1604 marshal() ([]byte, error) 1605 unmarshal([]byte) bool 1606 } 1607 1608 type handshakeMessageWithOriginalBytes interface { 1609 handshakeMessage 1610 1611 // originalBytes should return the original bytes that were passed to 1612 // unmarshal to create the message. If the message was not produced by 1613 // unmarshal, it should return nil. 1614 originalBytes() []byte 1615 } 1616 1617 // lruSessionCache is a ClientSessionCache implementation that uses an LRU 1618 // caching strategy. 1619 type lruSessionCache struct { 1620 sync.Mutex 1621 1622 m map[string]*list.Element 1623 q *list.List 1624 capacity int 1625 } 1626 1627 type lruSessionCacheEntry struct { 1628 sessionKey string 1629 state *ClientSessionState 1630 } 1631 1632 // NewLRUClientSessionCache returns a [ClientSessionCache] with the given 1633 // capacity that uses an LRU strategy. If capacity is < 1, a default capacity 1634 // is used instead. 1635 func NewLRUClientSessionCache(capacity int) ClientSessionCache { 1636 const defaultSessionCacheCapacity = 64 1637 1638 if capacity < 1 { 1639 capacity = defaultSessionCacheCapacity 1640 } 1641 return &lruSessionCache{ 1642 m: make(map[string]*list.Element), 1643 q: list.New(), 1644 capacity: capacity, 1645 } 1646 } 1647 1648 // Put adds the provided (sessionKey, cs) pair to the cache. If cs is nil, the entry 1649 // corresponding to sessionKey is removed from the cache instead. 1650 func (c *lruSessionCache) Put(sessionKey string, cs *ClientSessionState) { 1651 c.Lock() 1652 defer c.Unlock() 1653 1654 if elem, ok := c.m[sessionKey]; ok { 1655 if cs == nil { 1656 c.q.Remove(elem) 1657 delete(c.m, sessionKey) 1658 } else { 1659 entry := elem.Value.(*lruSessionCacheEntry) 1660 entry.state = cs 1661 c.q.MoveToFront(elem) 1662 } 1663 return 1664 } 1665 1666 if c.q.Len() < c.capacity { 1667 entry := &lruSessionCacheEntry{sessionKey, cs} 1668 c.m[sessionKey] = c.q.PushFront(entry) 1669 return 1670 } 1671 1672 elem := c.q.Back() 1673 entry := elem.Value.(*lruSessionCacheEntry) 1674 delete(c.m, entry.sessionKey) 1675 entry.sessionKey = sessionKey 1676 entry.state = cs 1677 c.q.MoveToFront(elem) 1678 c.m[sessionKey] = elem 1679 } 1680 1681 // Get returns the [ClientSessionState] value associated with a given key. It 1682 // returns (nil, false) if no value is found. 1683 func (c *lruSessionCache) Get(sessionKey string) (*ClientSessionState, bool) { 1684 c.Lock() 1685 defer c.Unlock() 1686 1687 if elem, ok := c.m[sessionKey]; ok { 1688 c.q.MoveToFront(elem) 1689 return elem.Value.(*lruSessionCacheEntry).state, true 1690 } 1691 return nil, false 1692 } 1693 1694 var emptyConfig Config 1695 1696 func defaultConfig() *Config { 1697 return &emptyConfig 1698 } 1699 1700 func unexpectedMessageError(wanted, got any) error { 1701 return fmt.Errorf("tls: received unexpected handshake message of type %T when waiting for %T", got, wanted) 1702 } 1703 1704 var testingOnlySupportedSignatureAlgorithms []SignatureScheme 1705 1706 // supportedSignatureAlgorithms returns the supported signature algorithms for 1707 // the given minimum TLS version, to advertise in ClientHello and 1708 // CertificateRequest messages. 1709 func supportedSignatureAlgorithms(minVers uint16) []SignatureScheme { 1710 sigAlgs := defaultSupportedSignatureAlgorithms() 1711 if testingOnlySupportedSignatureAlgorithms != nil { 1712 sigAlgs = slices.Clone(testingOnlySupportedSignatureAlgorithms) 1713 } 1714 return slices.DeleteFunc(sigAlgs, func(s SignatureScheme) bool { 1715 return isDisabledSignatureAlgorithm(minVers, s, false) 1716 }) 1717 } 1718 1719 var tlssha1 = godebug.New("tlssha1") 1720 1721 func isDisabledSignatureAlgorithm(version uint16, s SignatureScheme, isCert bool) bool { 1722 if fips140tls.Required() && !slices.Contains(allowedSignatureAlgorithmsFIPS, s) { 1723 return true 1724 } 1725 1726 // For the _cert extension we include all algorithms, including SHA-1 and 1727 // PKCS#1 v1.5, because it's more likely that something on our side will be 1728 // willing to accept a *-with-SHA1 certificate (e.g. with a custom 1729 // VerifyConnection or by a direct match with the CertPool), than that the 1730 // peer would have a better certificate but is just choosing not to send it. 1731 // crypto/x509 will refuse to verify important SHA-1 signatures anyway. 1732 if isCert { 1733 return false 1734 } 1735 1736 // TLS 1.3 removed support for PKCS#1 v1.5 and SHA-1 signatures, 1737 // and Go 1.25 removed support for SHA-1 signatures in TLS 1.2. 1738 if version > VersionTLS12 { 1739 sigType, sigHash, _ := typeAndHashFromSignatureScheme(s) 1740 if sigType == signaturePKCS1v15 || sigHash == crypto.SHA1 { 1741 return true 1742 } 1743 } else if tlssha1.Value() != "1" { 1744 _, sigHash, _ := typeAndHashFromSignatureScheme(s) 1745 if sigHash == crypto.SHA1 { 1746 return true 1747 } 1748 } 1749 1750 return false 1751 } 1752 1753 // supportedSignatureAlgorithmsCert returns the supported algorithms for 1754 // signatures in certificates. 1755 func supportedSignatureAlgorithmsCert() []SignatureScheme { 1756 sigAlgs := defaultSupportedSignatureAlgorithms() 1757 return slices.DeleteFunc(sigAlgs, func(s SignatureScheme) bool { 1758 return isDisabledSignatureAlgorithm(0, s, true) 1759 }) 1760 } 1761 1762 func isSupportedSignatureAlgorithm(sigAlg SignatureScheme, supportedSignatureAlgorithms []SignatureScheme) bool { 1763 return slices.Contains(supportedSignatureAlgorithms, sigAlg) 1764 } 1765 1766 // CertificateVerificationError is returned when certificate verification fails during the handshake. 1767 type CertificateVerificationError struct { 1768 // UnverifiedCertificates and its contents should not be modified. 1769 UnverifiedCertificates []*x509.Certificate 1770 Err error 1771 } 1772 1773 func (e *CertificateVerificationError) Error() string { 1774 return fmt.Sprintf("tls: failed to verify certificate: %s", e.Err) 1775 } 1776 1777 func (e *CertificateVerificationError) Unwrap() error { 1778 return e.Err 1779 } 1780 1781 // fipsAllowedChains returns chains that are allowed to be used in a TLS connection 1782 // based on the current fips140tls enforcement setting. 1783 // 1784 // If fips140tls is not required, the chains are returned as-is with no processing. 1785 // Otherwise, the returned chains are filtered to only those allowed by FIPS 140-3. 1786 // If this results in no chains it returns an error. 1787 func fipsAllowedChains(chains [][]*x509.Certificate) ([][]*x509.Certificate, error) { 1788 if !fips140tls.Required() { 1789 return chains, nil 1790 } 1791 1792 permittedChains := make([][]*x509.Certificate, 0, len(chains)) 1793 for _, chain := range chains { 1794 if fipsAllowChain(chain) { 1795 permittedChains = append(permittedChains, chain) 1796 } 1797 } 1798 1799 if len(permittedChains) == 0 { 1800 return nil, errors.New("tls: no FIPS compatible certificate chains found") 1801 } 1802 1803 return permittedChains, nil 1804 } 1805 1806 func fipsAllowChain(chain []*x509.Certificate) bool { 1807 if len(chain) == 0 { 1808 return false 1809 } 1810 1811 for _, cert := range chain { 1812 if !isCertificateAllowedFIPS(cert) { 1813 return false 1814 } 1815 } 1816 1817 return true 1818 } 1819 1820 // anyValidVerifiedChain reports if at least one of the chains in verifiedChains 1821 // is valid, as indicated by none of the certificates being expired and the root 1822 // being in opts.Roots (or in the system root pool if opts.Roots is nil). If 1823 // verifiedChains is empty, it returns false. 1824 func anyValidVerifiedChain(verifiedChains [][]*x509.Certificate, opts x509.VerifyOptions) bool { 1825 for _, chain := range verifiedChains { 1826 if len(chain) == 0 { 1827 continue 1828 } 1829 if slices.ContainsFunc(chain, func(cert *x509.Certificate) bool { 1830 return opts.CurrentTime.Before(cert.NotBefore) || opts.CurrentTime.After(cert.NotAfter) 1831 }) { 1832 continue 1833 } 1834 // Since we already validated the chain, we only care that it is rooted 1835 // in a CA in opts.Roots. On platforms where we control chain validation 1836 // (e.g. not Windows or macOS) this is a simple lookup in the CertPool 1837 // internal hash map, which we can simulate by running Verify on the 1838 // root. On other platforms, we have to do full verification again, 1839 // because EKU handling might differ. We will want to replace this with 1840 // CertPool.Contains if/once that is available. See go.dev/issue/77376. 1841 if runtime.GOOS == "windows" || runtime.GOOS == "darwin" || runtime.GOOS == "ios" { 1842 opts.Intermediates = x509.NewCertPool() 1843 for _, cert := range chain[1:max(1, len(chain)-1)] { 1844 opts.Intermediates.AddCert(cert) 1845 } 1846 leaf := chain[0] 1847 if _, err := leaf.Verify(opts); err == nil { 1848 return true 1849 } 1850 } else { 1851 root := chain[len(chain)-1] 1852 if _, err := root.Verify(opts); err == nil { 1853 return true 1854 } 1855 } 1856 } 1857 return false 1858 } 1859