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