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.
35 // Deprecated: SSLv3 is cryptographically broken, and is no longer
36 // supported by this package. See golang.org/issue/32716.
40 // VersionName returns the name for the provided TLS version number
41 // (e.g. "TLS 1.3"), or a fallback representation of the value if the
42 // version is not implemented by this package.
43 func VersionName(version uint16) string {
56 return fmt.Sprintf("0x%04X", version)
61 maxPlaintext = 16384 // maximum plaintext payload length
62 maxCiphertext = 16384 + 2048 // maximum ciphertext payload length
63 maxCiphertextTLS13 = 16384 + 256 // maximum ciphertext length in TLS 1.3
64 recordHeaderLen = 5 // record header length
65 maxHandshake = 65536 // maximum handshake we support (protocol max is 16 MB)
66 maxUselessRecords = 16 // maximum number of consecutive non-advancing records
73 recordTypeChangeCipherSpec recordType = 20
74 recordTypeAlert recordType = 21
75 recordTypeHandshake recordType = 22
76 recordTypeApplicationData recordType = 23
79 // TLS handshake message types.
81 typeHelloRequest uint8 = 0
82 typeClientHello uint8 = 1
83 typeServerHello uint8 = 2
84 typeNewSessionTicket uint8 = 4
85 typeEndOfEarlyData uint8 = 5
86 typeEncryptedExtensions uint8 = 8
87 typeCertificate uint8 = 11
88 typeServerKeyExchange uint8 = 12
89 typeCertificateRequest uint8 = 13
90 typeServerHelloDone uint8 = 14
91 typeCertificateVerify uint8 = 15
92 typeClientKeyExchange uint8 = 16
93 typeFinished uint8 = 20
94 typeCertificateStatus uint8 = 22
95 typeKeyUpdate uint8 = 24
96 typeNextProtocol uint8 = 67 // Not IANA assigned
97 typeMessageHash uint8 = 254 // synthetic message
100 // TLS compression types.
102 compressionNone uint8 = 0
105 // TLS extension numbers
107 extensionServerName uint16 = 0
108 extensionStatusRequest uint16 = 5
109 extensionSupportedCurves uint16 = 10 // supported_groups in TLS 1.3, see RFC 8446, Section 4.2.7
110 extensionSupportedPoints uint16 = 11
111 extensionSignatureAlgorithms uint16 = 13
112 extensionALPN uint16 = 16
113 extensionSCT uint16 = 18
114 extensionExtendedMasterSecret uint16 = 23
115 extensionSessionTicket uint16 = 35
116 extensionPreSharedKey uint16 = 41
117 extensionEarlyData uint16 = 42
118 extensionSupportedVersions uint16 = 43
119 extensionCookie uint16 = 44
120 extensionPSKModes uint16 = 45
121 extensionCertificateAuthorities uint16 = 47
122 extensionSignatureAlgorithmsCert uint16 = 50
123 extensionKeyShare uint16 = 51
124 extensionQUICTransportParameters uint16 = 57
125 extensionRenegotiationInfo uint16 = 0xff01
128 // TLS signaling cipher suite values
130 scsvRenegotiation uint16 = 0x00ff
133 // CurveID is the type of a TLS identifier for an elliptic curve. See
134 // https://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-8.
136 // In TLS 1.3, this type is called NamedGroup, but at this time this library
137 // only supports Elliptic Curve based groups. See RFC 8446, Section 4.2.7.
141 CurveP256 CurveID = 23
142 CurveP384 CurveID = 24
143 CurveP521 CurveID = 25
147 // TLS 1.3 Key Share. See RFC 8446, Section 4.2.8.
148 type keyShare struct {
153 // TLS 1.3 PSK Key Exchange Modes. See RFC 8446, Section 4.2.9.
155 pskModePlain uint8 = 0
159 // TLS 1.3 PSK Identity. Can be a Session Ticket, or a reference to a saved
160 // session. See RFC 8446, Section 4.2.11.
161 type pskIdentity struct {
163 obfuscatedTicketAge uint32
166 // TLS Elliptic Curve Point Formats
167 // https://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-9
169 pointFormatUncompressed uint8 = 0
172 // TLS CertificateStatusType (RFC 3546)
174 statusTypeOCSP uint8 = 1
177 // Certificate types (for certificateRequestMsg)
180 certTypeECDSASign = 64 // ECDSA or EdDSA keys, see RFC 8422, Section 3.
183 // Signature algorithms (for internal signaling use). Starting at 225 to avoid overlap with
184 // TLS 1.2 codepoints (RFC 5246, Appendix A.4.1), with which these have nothing to do.
186 signaturePKCS1v15 uint8 = iota + 225
192 // directSigning is a standard Hash value that signals that no pre-hashing
193 // should be performed, and that the input should be signed directly. It is the
194 // hash function associated with the Ed25519 signature scheme.
195 var directSigning crypto.Hash = 0
197 // defaultSupportedSignatureAlgorithms contains the signature and hash algorithms that
198 // the code advertises as supported in a TLS 1.2+ ClientHello and in a TLS 1.2+
199 // CertificateRequest. The two fields are merged to match with TLS 1.3.
200 // Note that in TLS 1.2, the ECDSA algorithms are not constrained to P-256, etc.
201 var defaultSupportedSignatureAlgorithms = []SignatureScheme{
203 ECDSAWithP256AndSHA256,
210 ECDSAWithP384AndSHA384,
211 ECDSAWithP521AndSHA512,
216 // helloRetryRequestRandom is set as the Random value of a ServerHello
217 // to signal that the message is actually a HelloRetryRequest.
218 var helloRetryRequestRandom = []byte{ // See RFC 8446, Section 4.1.3.
219 0xCF, 0x21, 0xAD, 0x74, 0xE5, 0x9A, 0x61, 0x11,
220 0xBE, 0x1D, 0x8C, 0x02, 0x1E, 0x65, 0xB8, 0x91,
221 0xC2, 0xA2, 0x11, 0x16, 0x7A, 0xBB, 0x8C, 0x5E,
222 0x07, 0x9E, 0x09, 0xE2, 0xC8, 0xA8, 0x33, 0x9C,
226 // downgradeCanaryTLS12 or downgradeCanaryTLS11 is embedded in the server
227 // random as a downgrade protection if the server would be capable of
228 // negotiating a higher version. See RFC 8446, Section 4.1.3.
229 downgradeCanaryTLS12 = "DOWNGRD\x01"
230 downgradeCanaryTLS11 = "DOWNGRD\x00"
233 // testingOnlyForceDowngradeCanary is set in tests to force the server side to
234 // include downgrade canaries even if it's using its highers supported version.
235 var testingOnlyForceDowngradeCanary bool
237 // ConnectionState records basic TLS details about the connection.
238 type ConnectionState struct {
239 // Version is the TLS version used by the connection (e.g. VersionTLS12).
242 // HandshakeComplete is true if the handshake has concluded.
243 HandshakeComplete bool
245 // DidResume is true if this connection was successfully resumed from a
246 // previous session with a session ticket or similar mechanism.
249 // CipherSuite is the cipher suite negotiated for the connection (e.g.
250 // TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, TLS_AES_128_GCM_SHA256).
253 // NegotiatedProtocol is the application protocol negotiated with ALPN.
254 NegotiatedProtocol string
256 // NegotiatedProtocolIsMutual used to indicate a mutual NPN negotiation.
258 // Deprecated: this value is always true.
259 NegotiatedProtocolIsMutual bool
261 // ServerName is the value of the Server Name Indication extension sent by
262 // the client. It's available both on the server and on the client side.
265 // PeerCertificates are the parsed certificates sent by the peer, in the
266 // order in which they were sent. The first element is the leaf certificate
267 // that the connection is verified against.
269 // On the client side, it can't be empty. On the server side, it can be
270 // empty if Config.ClientAuth is not RequireAnyClientCert or
271 // RequireAndVerifyClientCert.
273 // PeerCertificates and its contents should not be modified.
274 PeerCertificates []*x509.Certificate
276 // VerifiedChains is a list of one or more chains where the first element is
277 // PeerCertificates[0] and the last element is from Config.RootCAs (on the
278 // client side) or Config.ClientCAs (on the server side).
280 // On the client side, it's set if Config.InsecureSkipVerify is false. On
281 // the server side, it's set if Config.ClientAuth is VerifyClientCertIfGiven
282 // (and the peer provided a certificate) or RequireAndVerifyClientCert.
284 // VerifiedChains and its contents should not be modified.
285 VerifiedChains [][]*x509.Certificate
287 // SignedCertificateTimestamps is a list of SCTs provided by the peer
288 // through the TLS handshake for the leaf certificate, if any.
289 SignedCertificateTimestamps [][]byte
291 // OCSPResponse is a stapled Online Certificate Status Protocol (OCSP)
292 // response provided by the peer for the leaf certificate, if any.
295 // TLSUnique contains the "tls-unique" channel binding value (see RFC 5929,
296 // Section 3). This value will be nil for TLS 1.3 connections and for
297 // resumed connections that don't support Extended Master Secret (RFC 7627).
300 // ekm is a closure exposed via ExportKeyingMaterial.
301 ekm func(label string, context []byte, length int) ([]byte, error)
304 // ExportKeyingMaterial returns length bytes of exported key material in a new
305 // slice as defined in RFC 5705. If context is nil, it is not used as part of
306 // the seed. If the connection was set to allow renegotiation via
307 // Config.Renegotiation, this function will return an error.
309 // There are conditions in which the returned values might not be unique to a
310 // connection. See the Security Considerations sections of RFC 5705 and RFC 7627,
311 // and https://mitls.org/pages/attacks/3SHAKE#channelbindings.
312 func (cs *ConnectionState) ExportKeyingMaterial(label string, context []byte, length int) ([]byte, error) {
313 return cs.ekm(label, context, length)
316 // ClientAuthType declares the policy the server will follow for
317 // TLS Client Authentication.
318 type ClientAuthType int
321 // NoClientCert indicates that no client certificate should be requested
322 // during the handshake, and if any certificates are sent they will not
324 NoClientCert ClientAuthType = iota
325 // RequestClientCert indicates that a client certificate should be requested
326 // during the handshake, but does not require that the client send any
329 // RequireAnyClientCert indicates that a client certificate should be requested
330 // during the handshake, and that at least one certificate is required to be
331 // sent by the client, but that certificate is not required to be valid.
333 // VerifyClientCertIfGiven indicates that a client certificate should be requested
334 // during the handshake, but does not require that the client sends a
335 // certificate. If the client does send a certificate it is required to be
337 VerifyClientCertIfGiven
338 // RequireAndVerifyClientCert indicates that a client certificate should be requested
339 // during the handshake, and that at least one valid certificate is required
340 // to be sent by the client.
341 RequireAndVerifyClientCert
344 // requiresClientCert reports whether the ClientAuthType requires a client
345 // certificate to be provided.
346 func requiresClientCert(c ClientAuthType) bool {
348 case RequireAnyClientCert, RequireAndVerifyClientCert:
355 // ClientSessionCache is a cache of ClientSessionState objects that can be used
356 // by a client to resume a TLS session with a given server. ClientSessionCache
357 // implementations should expect to be called concurrently from different
358 // goroutines. Up to TLS 1.2, only ticket-based resumption is supported, not
359 // SessionID-based resumption. In TLS 1.3 they were merged into PSK modes, which
360 // are supported via this interface.
361 type ClientSessionCache interface {
362 // Get searches for a ClientSessionState associated with the given key.
363 // On return, ok is true if one was found.
364 Get(sessionKey string) (session *ClientSessionState, ok bool)
366 // Put adds the ClientSessionState to the cache with the given key. It might
367 // get called multiple times in a connection if a TLS 1.3 server provides
368 // more than one session ticket. If called with a nil *ClientSessionState,
369 // it should remove the cache entry.
370 Put(sessionKey string, cs *ClientSessionState)
373 //go:generate stringer -type=SignatureScheme,CurveID,ClientAuthType -output=common_string.go
375 // SignatureScheme identifies a signature algorithm supported by TLS. See
376 // RFC 8446, Section 4.2.3.
377 type SignatureScheme uint16
380 // RSASSA-PKCS1-v1_5 algorithms.
381 PKCS1WithSHA256 SignatureScheme = 0x0401
382 PKCS1WithSHA384 SignatureScheme = 0x0501
383 PKCS1WithSHA512 SignatureScheme = 0x0601
385 // RSASSA-PSS algorithms with public key OID rsaEncryption.
386 PSSWithSHA256 SignatureScheme = 0x0804
387 PSSWithSHA384 SignatureScheme = 0x0805
388 PSSWithSHA512 SignatureScheme = 0x0806
390 // ECDSA algorithms. Only constrained to a specific curve in TLS 1.3.
391 ECDSAWithP256AndSHA256 SignatureScheme = 0x0403
392 ECDSAWithP384AndSHA384 SignatureScheme = 0x0503
393 ECDSAWithP521AndSHA512 SignatureScheme = 0x0603
396 Ed25519 SignatureScheme = 0x0807
398 // Legacy signature and hash algorithms for TLS 1.2.
399 PKCS1WithSHA1 SignatureScheme = 0x0201
400 ECDSAWithSHA1 SignatureScheme = 0x0203
403 // ClientHelloInfo contains information from a ClientHello message in order to
404 // guide application logic in the GetCertificate and GetConfigForClient callbacks.
405 type ClientHelloInfo struct {
406 // CipherSuites lists the CipherSuites supported by the client (e.g.
407 // TLS_AES_128_GCM_SHA256, TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256).
408 CipherSuites []uint16
410 // ServerName indicates the name of the server requested by the client
411 // in order to support virtual hosting. ServerName is only set if the
412 // client is using SNI (see RFC 4366, Section 3.1).
415 // SupportedCurves lists the elliptic curves supported by the client.
416 // SupportedCurves is set only if the Supported Elliptic Curves
417 // Extension is being used (see RFC 4492, Section 5.1.1).
418 SupportedCurves []CurveID
420 // SupportedPoints lists the point formats supported by the client.
421 // SupportedPoints is set only if the Supported Point Formats Extension
422 // is being used (see RFC 4492, Section 5.1.2).
423 SupportedPoints []uint8
425 // SignatureSchemes lists the signature and hash schemes that the client
426 // is willing to verify. SignatureSchemes is set only if the Signature
427 // Algorithms Extension is being used (see RFC 5246, Section 7.4.1.4.1).
428 SignatureSchemes []SignatureScheme
430 // SupportedProtos lists the application protocols supported by the client.
431 // SupportedProtos is set only if the Application-Layer Protocol
432 // Negotiation Extension is being used (see RFC 7301, Section 3.1).
434 // Servers can select a protocol by setting Config.NextProtos in a
435 // GetConfigForClient return value.
436 SupportedProtos []string
438 // SupportedVersions lists the TLS versions supported by the client.
439 // For TLS versions less than 1.3, this is extrapolated from the max
440 // version advertised by the client, so values other than the greatest
441 // might be rejected if used.
442 SupportedVersions []uint16
444 // Conn is the underlying net.Conn for the connection. Do not read
445 // from, or write to, this connection; that will cause the TLS
446 // connection to fail.
449 // config is embedded by the GetCertificate or GetConfigForClient caller,
450 // for use with SupportsCertificate.
453 // ctx is the context of the handshake that is in progress.
457 // Context returns the context of the handshake that is in progress.
458 // This context is a child of the context passed to HandshakeContext,
459 // if any, and is canceled when the handshake concludes.
460 func (c *ClientHelloInfo) Context() context.Context {
464 // CertificateRequestInfo contains information from a server's
465 // CertificateRequest message, which is used to demand a certificate and proof
466 // of control from a client.
467 type CertificateRequestInfo struct {
468 // AcceptableCAs contains zero or more, DER-encoded, X.501
469 // Distinguished Names. These are the names of root or intermediate CAs
470 // that the server wishes the returned certificate to be signed by. An
471 // empty slice indicates that the server has no preference.
472 AcceptableCAs [][]byte
474 // SignatureSchemes lists the signature schemes that the server is
475 // willing to verify.
476 SignatureSchemes []SignatureScheme
478 // Version is the TLS version that was negotiated for this connection.
481 // ctx is the context of the handshake that is in progress.
485 // Context returns the context of the handshake that is in progress.
486 // This context is a child of the context passed to HandshakeContext,
487 // if any, and is canceled when the handshake concludes.
488 func (c *CertificateRequestInfo) Context() context.Context {
492 // RenegotiationSupport enumerates the different levels of support for TLS
493 // renegotiation. TLS renegotiation is the act of performing subsequent
494 // handshakes on a connection after the first. This significantly complicates
495 // the state machine and has been the source of numerous, subtle security
496 // issues. Initiating a renegotiation is not supported, but support for
497 // accepting renegotiation requests may be enabled.
499 // Even when enabled, the server may not change its identity between handshakes
500 // (i.e. the leaf certificate must be the same). Additionally, concurrent
501 // handshake and application data flow is not permitted so renegotiation can
502 // only be used with protocols that synchronise with the renegotiation, such as
505 // Renegotiation is not defined in TLS 1.3.
506 type RenegotiationSupport int
509 // RenegotiateNever disables renegotiation.
510 RenegotiateNever RenegotiationSupport = iota
512 // RenegotiateOnceAsClient allows a remote server to request
513 // renegotiation once per connection.
514 RenegotiateOnceAsClient
516 // RenegotiateFreelyAsClient allows a remote server to repeatedly
517 // request renegotiation.
518 RenegotiateFreelyAsClient
521 // A Config structure is used to configure a TLS client or server.
522 // After one has been passed to a TLS function it must not be
523 // modified. A Config may be reused; the tls package will also not
526 // Rand provides the source of entropy for nonces and RSA blinding.
527 // If Rand is nil, TLS uses the cryptographic random reader in package
529 // The Reader must be safe for use by multiple goroutines.
532 // Time returns the current time as the number of seconds since the epoch.
533 // If Time is nil, TLS uses time.Now.
534 Time func() time.Time
536 // Certificates contains one or more certificate chains to present to the
537 // other side of the connection. The first certificate compatible with the
538 // peer's requirements is selected automatically.
540 // Server configurations must set one of Certificates, GetCertificate or
541 // GetConfigForClient. Clients doing client-authentication may set either
542 // Certificates or GetClientCertificate.
544 // Note: if there are multiple Certificates, and they don't have the
545 // optional field Leaf set, certificate selection will incur a significant
546 // per-handshake performance cost.
547 Certificates []Certificate
549 // NameToCertificate maps from a certificate name to an element of
550 // Certificates. Note that a certificate name can be of the form
551 // '*.example.com' and so doesn't have to be a domain name as such.
553 // Deprecated: NameToCertificate only allows associating a single
554 // certificate with a given name. Leave this field nil to let the library
555 // select the first compatible chain from Certificates.
556 NameToCertificate map[string]*Certificate
558 // GetCertificate returns a Certificate based on the given
559 // ClientHelloInfo. It will only be called if the client supplies SNI
560 // information or if Certificates is empty.
562 // If GetCertificate is nil or returns nil, then the certificate is
563 // retrieved from NameToCertificate. If NameToCertificate is nil, the
564 // best element of Certificates will be used.
566 // Once a Certificate is returned it should not be modified.
567 GetCertificate func(*ClientHelloInfo) (*Certificate, error)
569 // GetClientCertificate, if not nil, is called when a server requests a
570 // certificate from a client. If set, the contents of Certificates will
573 // If GetClientCertificate returns an error, the handshake will be
574 // aborted and that error will be returned. Otherwise
575 // GetClientCertificate must return a non-nil Certificate. If
576 // Certificate.Certificate is empty then no certificate will be sent to
577 // the server. If this is unacceptable to the server then it may abort
580 // GetClientCertificate may be called multiple times for the same
581 // connection if renegotiation occurs or if TLS 1.3 is in use.
583 // Once a Certificate is returned it should not be modified.
584 GetClientCertificate func(*CertificateRequestInfo) (*Certificate, error)
586 // GetConfigForClient, if not nil, is called after a ClientHello is
587 // received from a client. It may return a non-nil Config in order to
588 // change the Config that will be used to handle this connection. If
589 // the returned Config is nil, the original Config will be used. The
590 // Config returned by this callback may not be subsequently modified.
592 // If GetConfigForClient is nil, the Config passed to Server() will be
593 // used for all connections.
595 // If SessionTicketKey was explicitly set on the returned Config, or if
596 // SetSessionTicketKeys was called on the returned Config, those keys will
597 // be used. Otherwise, the original Config keys will be used (and possibly
598 // rotated if they are automatically managed).
599 GetConfigForClient func(*ClientHelloInfo) (*Config, error)
601 // VerifyPeerCertificate, if not nil, is called after normal
602 // certificate verification by either a TLS client or server. It
603 // receives the raw ASN.1 certificates provided by the peer and also
604 // any verified chains that normal processing found. If it returns a
605 // non-nil error, the handshake is aborted and that error results.
607 // If normal verification fails then the handshake will abort before
608 // considering this callback. If normal verification is disabled (on the
609 // client when InsecureSkipVerify is set, or on a server when ClientAuth is
610 // RequestClientCert or RequireAnyClientCert), then this callback will be
611 // considered but the verifiedChains argument will always be nil. When
612 // ClientAuth is NoClientCert, this callback is not called on the server.
613 // rawCerts may be empty on the server if ClientAuth is RequestClientCert or
614 // VerifyClientCertIfGiven.
616 // This callback is not invoked on resumed connections, as certificates are
617 // not re-verified on resumption.
619 // verifiedChains and its contents should not be modified.
620 VerifyPeerCertificate func(rawCerts [][]byte, verifiedChains [][]*x509.Certificate) error
622 // VerifyConnection, if not nil, is called after normal certificate
623 // verification and after VerifyPeerCertificate by either a TLS client
624 // or server. If it returns a non-nil error, the handshake is aborted
625 // and that error results.
627 // If normal verification fails then the handshake will abort before
628 // considering this callback. This callback will run for all connections,
629 // including resumptions, regardless of InsecureSkipVerify or ClientAuth
631 VerifyConnection func(ConnectionState) error
633 // RootCAs defines the set of root certificate authorities
634 // that clients use when verifying server certificates.
635 // If RootCAs is nil, TLS uses the host's root CA set.
636 RootCAs *x509.CertPool
638 // NextProtos is a list of supported application level protocols, in
639 // order of preference. If both peers support ALPN, the selected
640 // protocol will be one from this list, and the connection will fail
641 // if there is no mutually supported protocol. If NextProtos is empty
642 // or the peer doesn't support ALPN, the connection will succeed and
643 // ConnectionState.NegotiatedProtocol will be empty.
646 // ServerName is used to verify the hostname on the returned
647 // certificates unless InsecureSkipVerify is given. It is also included
648 // in the client's handshake to support virtual hosting unless it is
652 // ClientAuth determines the server's policy for
653 // TLS Client Authentication. The default is NoClientCert.
654 ClientAuth ClientAuthType
656 // ClientCAs defines the set of root certificate authorities
657 // that servers use if required to verify a client certificate
658 // by the policy in ClientAuth.
659 ClientCAs *x509.CertPool
661 // InsecureSkipVerify controls whether a client verifies the server's
662 // certificate chain and host name. If InsecureSkipVerify is true, crypto/tls
663 // accepts any certificate presented by the server and any host name in that
664 // certificate. In this mode, TLS is susceptible to machine-in-the-middle
665 // attacks unless custom verification is used. This should be used only for
666 // testing or in combination with VerifyConnection or VerifyPeerCertificate.
667 InsecureSkipVerify bool
669 // CipherSuites is a list of enabled TLS 1.0–1.2 cipher suites. The order of
670 // the list is ignored. Note that TLS 1.3 ciphersuites are not configurable.
672 // If CipherSuites is nil, a safe default list is used. The default cipher
673 // suites might change over time. In Go 1.22 RSA key exchange based cipher
674 // suites were removed from the default list, but can be re-added with the
675 // GODEBUG setting tlsrsakex=1.
676 CipherSuites []uint16
678 // PreferServerCipherSuites is a legacy field and has no effect.
680 // It used to control whether the server would follow the client's or the
681 // server's preference. Servers now select the best mutually supported
682 // cipher suite based on logic that takes into account inferred client
683 // hardware, server hardware, and security.
685 // Deprecated: PreferServerCipherSuites is ignored.
686 PreferServerCipherSuites bool
688 // SessionTicketsDisabled may be set to true to disable session ticket and
689 // PSK (resumption) support. Note that on clients, session ticket support is
690 // also disabled if ClientSessionCache is nil.
691 SessionTicketsDisabled bool
693 // SessionTicketKey is used by TLS servers to provide session resumption.
694 // See RFC 5077 and the PSK mode of RFC 8446. If zero, it will be filled
695 // with random data before the first server handshake.
697 // Deprecated: if this field is left at zero, session ticket keys will be
698 // automatically rotated every day and dropped after seven days. For
699 // customizing the rotation schedule or synchronizing servers that are
700 // terminating connections for the same host, use SetSessionTicketKeys.
701 SessionTicketKey [32]byte
703 // ClientSessionCache is a cache of ClientSessionState entries for TLS
704 // session resumption. It is only used by clients.
705 ClientSessionCache ClientSessionCache
707 // UnwrapSession is called on the server to turn a ticket/identity
708 // previously produced by [WrapSession] into a usable session.
710 // UnwrapSession will usually either decrypt a session state in the ticket
711 // (for example with [Config.EncryptTicket]), or use the ticket as a handle
712 // to recover a previously stored state. It must use [ParseSessionState] to
713 // deserialize the session state.
715 // If UnwrapSession returns an error, the connection is terminated. If it
716 // returns (nil, nil), the session is ignored. crypto/tls may still choose
717 // not to resume the returned session.
718 UnwrapSession func(identity []byte, cs ConnectionState) (*SessionState, error)
720 // WrapSession is called on the server to produce a session ticket/identity.
722 // WrapSession must serialize the session state with [SessionState.Bytes].
723 // It may then encrypt the serialized state (for example with
724 // [Config.DecryptTicket]) and use it as the ticket, or store the state and
725 // return a handle for it.
727 // If WrapSession returns an error, the connection is terminated.
729 // Warning: the return value will be exposed on the wire and to clients in
730 // plaintext. The application is in charge of encrypting and authenticating
731 // it (and rotating keys) or returning high-entropy identifiers. Failing to
732 // do so correctly can compromise current, previous, and future connections
733 // depending on the protocol version.
734 WrapSession func(ConnectionState, *SessionState) ([]byte, error)
736 // MinVersion contains the minimum TLS version that is acceptable.
738 // By default, TLS 1.2 is currently used as the minimum. TLS 1.0 is the
739 // minimum supported by this package.
741 // The server-side default can be reverted to TLS 1.0 by including the value
742 // "tls10server=1" in the GODEBUG environment variable.
745 // MaxVersion contains the maximum TLS version that is acceptable.
747 // By default, the maximum version supported by this package is used,
748 // which is currently TLS 1.3.
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
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
761 DynamicRecordSizingDisabled bool
763 // Renegotiation controls what types of renegotiation are supported.
764 // The default, none, is correct for the vast majority of applications.
765 Renegotiation RenegotiationSupport
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
775 // mutex protects sessionTicketKeys and autoSessionTicketKeys.
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
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
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
798 // ticketKey is the internal representation of a session ticket key.
799 type ticketKey struct {
802 // created is the time at which this ticket key was created. See Config.ticketKeys.
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()
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
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 {
832 defer c.mutex.RUnlock()
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,
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,
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")
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) {
881 // We need to write some data, so get an exclusive lock and re-check any conditions.
883 defer c.mutex.RLock()
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))
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)}
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 {
918 configForClient.initLegacySessionTicketKeyRLocked()
919 if len(configForClient.sessionTicketKeys) != 0 {
920 ret := configForClient.sessionTicketKeys
921 configForClient.mutex.RUnlock()
924 configForClient.mutex.RUnlock()
928 defer c.mutex.RUnlock()
929 if c.SessionTicketsDisabled {
932 c.initLegacySessionTicketKeyRLocked()
933 if len(c.sessionTicketKeys) != 0 {
934 return c.sessionTicketKeys
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
941 // autoSessionTicketKeys are managed by auto-rotation.
943 defer c.mutex.RLock()
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 {
949 if _, err := io.ReadFull(c.rand(), newKey[:]); err != nil {
950 panic(fmt.Sprintf("unable to generate random session ticket key: %v", err))
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)
960 c.autoSessionTicketKeys = valid
962 return c.autoSessionTicketKeys
965 // SetSessionTicketKeys updates the session ticket keys for a server.
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.
972 // Calling this function will turn off automatic session ticket key rotation.
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
978 func (c *Config) SetSessionTicketKeys(keys [][32]byte) {
980 panic("tls: keys must have at least one key")
983 newKeys := make([]ticketKey, len(keys))
984 for i, bytes := range keys {
985 newKeys[i] = c.ticketKeyFromBytes(bytes)
989 c.sessionTicketKeys = newKeys
993 func (c *Config) rand() io.Reader {
1001 func (c *Config) time() time.Time {
1009 func (c *Config) cipherSuites() []uint16 {
1011 return fipsCipherSuites(c)
1013 if c.CipherSuites != nil {
1014 return c.CipherSuites
1016 return defaultCipherSuites
1019 var supportedVersions = []uint16{
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
1031 var tls10godebug = godebug.New("tls10server")
1033 func (c *Config) supportedVersions(isClient bool) []uint16 {
1034 versions := make([]uint16, 0, len(supportedVersions))
1035 for _, v := range supportedVersions {
1036 if needFIPS() && (v < fipsMinVersion(c) || v > fipsMaxVersion(c)) {
1039 if (c == nil || c.MinVersion == 0) && v < VersionTLS12 {
1040 if !isClient && tls10godebug.Value() == "1" {
1041 tls10godebug.IncNonDefault()
1046 if c != nil && c.MinVersion != 0 && v < c.MinVersion {
1049 if c != nil && c.MaxVersion != 0 && v > c.MaxVersion {
1052 versions = append(versions, v)
1057 func (c *Config) maxSupportedVersion(isClient bool) uint16 {
1058 supportedVersions := c.supportedVersions(isClient)
1059 if len(supportedVersions) == 0 {
1062 return supportedVersions[0]
1065 // supportedVersionsFromMax returns a list of supported versions derived from a
1066 // legacy maximum version value. Note that only versions supported by this
1067 // library are returned. Any newer peer will use supportedVersions anyway.
1068 func supportedVersionsFromMax(maxVersion uint16) []uint16 {
1069 versions := make([]uint16, 0, len(supportedVersions))
1070 for _, v := range supportedVersions {
1074 versions = append(versions, v)
1079 var defaultCurvePreferences = []CurveID{X25519, CurveP256, CurveP384, CurveP521}
1081 func (c *Config) curvePreferences() []CurveID {
1083 return fipsCurvePreferences(c)
1085 if c == nil || len(c.CurvePreferences) == 0 {
1086 return defaultCurvePreferences
1088 return c.CurvePreferences
1091 func (c *Config) supportsCurve(curve CurveID) bool {
1092 for _, cc := range c.curvePreferences() {
1100 // mutualVersion returns the protocol version to use given the advertised
1101 // versions of the peer. Priority is given to the peer preference order.
1102 func (c *Config) mutualVersion(isClient bool, peerVersions []uint16) (uint16, bool) {
1103 supportedVersions := c.supportedVersions(isClient)
1104 for _, peerVersion := range peerVersions {
1105 for _, v := range supportedVersions {
1106 if v == peerVersion {
1114 var errNoCertificates = errors.New("tls: no certificates configured")
1116 // getCertificate returns the best certificate for the given ClientHelloInfo,
1117 // defaulting to the first element of c.Certificates.
1118 func (c *Config) getCertificate(clientHello *ClientHelloInfo) (*Certificate, error) {
1119 if c.GetCertificate != nil &&
1120 (len(c.Certificates) == 0 || len(clientHello.ServerName) > 0) {
1121 cert, err := c.GetCertificate(clientHello)
1122 if cert != nil || err != nil {
1127 if len(c.Certificates) == 0 {
1128 return nil, errNoCertificates
1131 if len(c.Certificates) == 1 {
1132 // There's only one choice, so no point doing any work.
1133 return &c.Certificates[0], nil
1136 if c.NameToCertificate != nil {
1137 name := strings.ToLower(clientHello.ServerName)
1138 if cert, ok := c.NameToCertificate[name]; ok {
1142 labels := strings.Split(name, ".")
1144 wildcardName := strings.Join(labels, ".")
1145 if cert, ok := c.NameToCertificate[wildcardName]; ok {
1151 for _, cert := range c.Certificates {
1152 if err := clientHello.SupportsCertificate(&cert); err == nil {
1157 // If nothing matches, return the first certificate.
1158 return &c.Certificates[0], nil
1161 // SupportsCertificate returns nil if the provided certificate is supported by
1162 // the client that sent the ClientHello. Otherwise, it returns an error
1163 // describing the reason for the incompatibility.
1165 // If this [ClientHelloInfo] was passed to a GetConfigForClient or GetCertificate
1166 // callback, this method will take into account the associated [Config]. Note that
1167 // if GetConfigForClient returns a different [Config], the change can't be
1168 // accounted for by this method.
1170 // This function will call x509.ParseCertificate unless c.Leaf is set, which can
1171 // incur a significant performance cost.
1172 func (chi *ClientHelloInfo) SupportsCertificate(c *Certificate) error {
1173 // Note we don't currently support certificate_authorities nor
1174 // signature_algorithms_cert, and don't check the algorithms of the
1175 // signatures on the chain (which anyway are a SHOULD, see RFC 8446,
1176 // Section 4.4.2.2).
1178 config := chi.config
1182 vers, ok := config.mutualVersion(roleServer, chi.SupportedVersions)
1184 return errors.New("no mutually supported protocol versions")
1187 // If the client specified the name they are trying to connect to, the
1188 // certificate needs to be valid for it.
1189 if chi.ServerName != "" {
1190 x509Cert, err := c.leaf()
1192 return fmt.Errorf("failed to parse certificate: %w", err)
1194 if err := x509Cert.VerifyHostname(chi.ServerName); err != nil {
1195 return fmt.Errorf("certificate is not valid for requested server name: %w", err)
1199 // supportsRSAFallback returns nil if the certificate and connection support
1200 // the static RSA key exchange, and unsupported otherwise. The logic for
1201 // supporting static RSA is completely disjoint from the logic for
1202 // supporting signed key exchanges, so we just check it as a fallback.
1203 supportsRSAFallback := func(unsupported error) error {
1204 // TLS 1.3 dropped support for the static RSA key exchange.
1205 if vers == VersionTLS13 {
1208 // The static RSA key exchange works by decrypting a challenge with the
1209 // RSA private key, not by signing, so check the PrivateKey implements
1210 // crypto.Decrypter, like *rsa.PrivateKey does.
1211 if priv, ok := c.PrivateKey.(crypto.Decrypter); ok {
1212 if _, ok := priv.Public().(*rsa.PublicKey); !ok {
1218 // Finally, there needs to be a mutual cipher suite that uses the static
1219 // RSA key exchange instead of ECDHE.
1220 rsaCipherSuite := selectCipherSuite(chi.CipherSuites, config.cipherSuites(), func(c *cipherSuite) bool {
1221 if c.flags&suiteECDHE != 0 {
1224 if vers < VersionTLS12 && c.flags&suiteTLS12 != 0 {
1229 if rsaCipherSuite == nil {
1235 // If the client sent the signature_algorithms extension, ensure it supports
1236 // schemes we can use with this certificate and TLS version.
1237 if len(chi.SignatureSchemes) > 0 {
1238 if _, err := selectSignatureScheme(vers, c, chi.SignatureSchemes); err != nil {
1239 return supportsRSAFallback(err)
1243 // In TLS 1.3 we are done because supported_groups is only relevant to the
1244 // ECDHE computation, point format negotiation is removed, cipher suites are
1245 // only relevant to the AEAD choice, and static RSA does not exist.
1246 if vers == VersionTLS13 {
1250 // The only signed key exchange we support is ECDHE.
1251 if !supportsECDHE(config, chi.SupportedCurves, chi.SupportedPoints) {
1252 return supportsRSAFallback(errors.New("client doesn't support ECDHE, can only use legacy RSA key exchange"))
1255 var ecdsaCipherSuite bool
1256 if priv, ok := c.PrivateKey.(crypto.Signer); ok {
1257 switch pub := priv.Public().(type) {
1258 case *ecdsa.PublicKey:
1261 case elliptic.P256():
1263 case elliptic.P384():
1265 case elliptic.P521():
1268 return supportsRSAFallback(unsupportedCertificateError(c))
1271 for _, c := range chi.SupportedCurves {
1272 if c == curve && config.supportsCurve(c) {
1278 return errors.New("client doesn't support certificate curve")
1280 ecdsaCipherSuite = true
1281 case ed25519.PublicKey:
1282 if vers < VersionTLS12 || len(chi.SignatureSchemes) == 0 {
1283 return errors.New("connection doesn't support Ed25519")
1285 ecdsaCipherSuite = true
1286 case *rsa.PublicKey:
1288 return supportsRSAFallback(unsupportedCertificateError(c))
1291 return supportsRSAFallback(unsupportedCertificateError(c))
1294 // Make sure that there is a mutually supported cipher suite that works with
1295 // this certificate. Cipher suite selection will then apply the logic in
1296 // reverse to pick it. See also serverHandshakeState.cipherSuiteOk.
1297 cipherSuite := selectCipherSuite(chi.CipherSuites, config.cipherSuites(), func(c *cipherSuite) bool {
1298 if c.flags&suiteECDHE == 0 {
1301 if c.flags&suiteECSign != 0 {
1302 if !ecdsaCipherSuite {
1306 if ecdsaCipherSuite {
1310 if vers < VersionTLS12 && c.flags&suiteTLS12 != 0 {
1315 if cipherSuite == nil {
1316 return supportsRSAFallback(errors.New("client doesn't support any cipher suites compatible with the certificate"))
1322 // SupportsCertificate returns nil if the provided certificate is supported by
1323 // the server that sent the CertificateRequest. Otherwise, it returns an error
1324 // describing the reason for the incompatibility.
1325 func (cri *CertificateRequestInfo) SupportsCertificate(c *Certificate) error {
1326 if _, err := selectSignatureScheme(cri.Version, c, cri.SignatureSchemes); err != nil {
1330 if len(cri.AcceptableCAs) == 0 {
1334 for j, cert := range c.Certificate {
1336 // Parse the certificate if this isn't the leaf node, or if
1337 // chain.Leaf was nil.
1338 if j != 0 || x509Cert == nil {
1340 if x509Cert, err = x509.ParseCertificate(cert); err != nil {
1341 return fmt.Errorf("failed to parse certificate #%d in the chain: %w", j, err)
1345 for _, ca := range cri.AcceptableCAs {
1346 if bytes.Equal(x509Cert.RawIssuer, ca) {
1351 return errors.New("chain is not signed by an acceptable CA")
1354 // BuildNameToCertificate parses c.Certificates and builds c.NameToCertificate
1355 // from the CommonName and SubjectAlternateName fields of each of the leaf
1358 // Deprecated: NameToCertificate only allows associating a single certificate
1359 // with a given name. Leave that field nil to let the library select the first
1360 // compatible chain from Certificates.
1361 func (c *Config) BuildNameToCertificate() {
1362 c.NameToCertificate = make(map[string]*Certificate)
1363 for i := range c.Certificates {
1364 cert := &c.Certificates[i]
1365 x509Cert, err := cert.leaf()
1369 // If SANs are *not* present, some clients will consider the certificate
1370 // valid for the name in the Common Name.
1371 if x509Cert.Subject.CommonName != "" && len(x509Cert.DNSNames) == 0 {
1372 c.NameToCertificate[x509Cert.Subject.CommonName] = cert
1374 for _, san := range x509Cert.DNSNames {
1375 c.NameToCertificate[san] = cert
1381 keyLogLabelTLS12 = "CLIENT_RANDOM"
1382 keyLogLabelClientHandshake = "CLIENT_HANDSHAKE_TRAFFIC_SECRET"
1383 keyLogLabelServerHandshake = "SERVER_HANDSHAKE_TRAFFIC_SECRET"
1384 keyLogLabelClientTraffic = "CLIENT_TRAFFIC_SECRET_0"
1385 keyLogLabelServerTraffic = "SERVER_TRAFFIC_SECRET_0"
1388 func (c *Config) writeKeyLog(label string, clientRandom, secret []byte) error {
1389 if c.KeyLogWriter == nil {
1393 logLine := fmt.Appendf(nil, "%s %x %x\n", label, clientRandom, secret)
1396 _, err := c.KeyLogWriter.Write(logLine)
1397 writerMutex.Unlock()
1402 // writerMutex protects all KeyLogWriters globally. It is rarely enabled,
1403 // and is only for debugging, so a global mutex saves space.
1404 var writerMutex sync.Mutex
1406 // A Certificate is a chain of one or more certificates, leaf first.
1407 type Certificate struct {
1408 Certificate [][]byte
1409 // PrivateKey contains the private key corresponding to the public key in
1410 // Leaf. This must implement crypto.Signer with an RSA, ECDSA or Ed25519 PublicKey.
1411 // For a server up to TLS 1.2, it can also implement crypto.Decrypter with
1412 // an RSA PublicKey.
1413 PrivateKey crypto.PrivateKey
1414 // SupportedSignatureAlgorithms is an optional list restricting what
1415 // signature algorithms the PrivateKey can be used for.
1416 SupportedSignatureAlgorithms []SignatureScheme
1417 // OCSPStaple contains an optional OCSP response which will be served
1418 // to clients that request it.
1420 // SignedCertificateTimestamps contains an optional list of Signed
1421 // Certificate Timestamps which will be served to clients that request it.
1422 SignedCertificateTimestamps [][]byte
1423 // Leaf is the parsed form of the leaf certificate, which may be initialized
1424 // using x509.ParseCertificate to reduce per-handshake processing. If nil,
1425 // the leaf certificate will be parsed as needed.
1426 Leaf *x509.Certificate
1429 // leaf returns the parsed leaf certificate, either from c.Leaf or by parsing
1430 // the corresponding c.Certificate[0].
1431 func (c *Certificate) leaf() (*x509.Certificate, error) {
1435 return x509.ParseCertificate(c.Certificate[0])
1438 type handshakeMessage interface {
1439 marshal() ([]byte, error)
1440 unmarshal([]byte) bool
1443 // lruSessionCache is a ClientSessionCache implementation that uses an LRU
1444 // caching strategy.
1445 type lruSessionCache struct {
1448 m map[string]*list.Element
1453 type lruSessionCacheEntry struct {
1455 state *ClientSessionState
1458 // NewLRUClientSessionCache returns a [ClientSessionCache] with the given
1459 // capacity that uses an LRU strategy. If capacity is < 1, a default capacity
1461 func NewLRUClientSessionCache(capacity int) ClientSessionCache {
1462 const defaultSessionCacheCapacity = 64
1465 capacity = defaultSessionCacheCapacity
1467 return &lruSessionCache{
1468 m: make(map[string]*list.Element),
1474 // Put adds the provided (sessionKey, cs) pair to the cache. If cs is nil, the entry
1475 // corresponding to sessionKey is removed from the cache instead.
1476 func (c *lruSessionCache) Put(sessionKey string, cs *ClientSessionState) {
1480 if elem, ok := c.m[sessionKey]; ok {
1483 delete(c.m, sessionKey)
1485 entry := elem.Value.(*lruSessionCacheEntry)
1487 c.q.MoveToFront(elem)
1492 if c.q.Len() < c.capacity {
1493 entry := &lruSessionCacheEntry{sessionKey, cs}
1494 c.m[sessionKey] = c.q.PushFront(entry)
1499 entry := elem.Value.(*lruSessionCacheEntry)
1500 delete(c.m, entry.sessionKey)
1501 entry.sessionKey = sessionKey
1503 c.q.MoveToFront(elem)
1504 c.m[sessionKey] = elem
1507 // Get returns the [ClientSessionState] value associated with a given key. It
1508 // returns (nil, false) if no value is found.
1509 func (c *lruSessionCache) Get(sessionKey string) (*ClientSessionState, bool) {
1513 if elem, ok := c.m[sessionKey]; ok {
1514 c.q.MoveToFront(elem)
1515 return elem.Value.(*lruSessionCacheEntry).state, true
1520 var emptyConfig Config
1522 func defaultConfig() *Config {
1526 func unexpectedMessageError(wanted, got any) error {
1527 return fmt.Errorf("tls: received unexpected handshake message of type %T when waiting for %T", got, wanted)
1530 func isSupportedSignatureAlgorithm(sigAlg SignatureScheme, supportedSignatureAlgorithms []SignatureScheme) bool {
1531 for _, s := range supportedSignatureAlgorithms {
1539 // CertificateVerificationError is returned when certificate verification fails during the handshake.
1540 type CertificateVerificationError struct {
1541 // UnverifiedCertificates and its contents should not be modified.
1542 UnverifiedCertificates []*x509.Certificate
1546 func (e *CertificateVerificationError) Error() string {
1547 return fmt.Sprintf("tls: failed to verify certificate: %s", e.Err)
1550 func (e *CertificateVerificationError) Unwrap() error {