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