tlsx

type AlertError uint8

type Certificate struct {
	Certificate [][]byte
	// PrivateKey contains the private key corresponding to the public key in
	// Leaf. This must implement [crypto.Signer] with an RSA, ECDSA, Ed25519
	// (TLS 1.2+), or ML-DSA (TLS 1.3) PublicKey.
	//
	// For a server up to TLS 1.2, it can also implement crypto.Decrypter with
	// an RSA PublicKey.
	//
	// If it implements [crypto.MessageSigner], SignMessage will be used instead
	// of Sign for TLS 1.2 and later.
	PrivateKey crypto.PrivateKey
	// SupportedSignatureAlgorithms is an optional list restricting what
	// signature algorithms the PrivateKey can be used for.
	SupportedSignatureAlgorithms []SignatureScheme
	// OCSPStaple contains an optional OCSP response which will be served
	// to clients that request it.
	OCSPStaple []byte
	// SignedCertificateTimestamps contains an optional list of Signed
	// Certificate Timestamps which will be served to clients that request it.
	SignedCertificateTimestamps [][]byte
	// ChainOCSPStaples (tlsx) are OCSP responses for Certificate[1:], index
	// i for Certificate[i+1] (nil for none): sent per certificate entry in
	// TLS 1.3 and in an ocsp_multi CertificateStatus (RFC 6961) in TLS 1.2.
	ChainOCSPStaples [][]byte
	// Leaf is the parsed form of the leaf certificate, which may be initialized
	// using x509.ParseCertificate to reduce per-handshake processing. If nil,
	// the leaf certificate will be parsed as needed.
	Leaf *x509.Certificate
}

type CertificateRequestInfo struct {
	// AcceptableCAs contains zero or more, DER-encoded, X.501
	// Distinguished Names. These are the names of root or intermediate CAs
	// that the server wishes the returned certificate to be signed by. An
	// empty slice indicates that the server has no preference.
	AcceptableCAs [][]byte

	// SignatureSchemes lists the signature schemes that the server is
	// willing to verify.
	SignatureSchemes []SignatureScheme

	// Version is the TLS version that was negotiated for this connection.
	Version uint16
	// contains filtered or unexported fields
}

type CertificateVerificationError struct {
	// UnverifiedCertificates and its contents should not be modified.
	UnverifiedCertificates []*x509.Certificate
	Err                    error
}

type CipherSuite struct {
	ID   uint16
	Name string

	// Supported versions is the list of TLS protocol versions that can
	// negotiate this cipher suite.
	SupportedVersions []uint16

	// Insecure is true if the cipher suite has known security issues
	// due to its primitives, design, or implementation.
	Insecure bool
}

type ClientAuthType int

type ClientHelloInfo struct {
	// CipherSuites lists the CipherSuites supported by the client (e.g.
	// TLS_AES_128_GCM_SHA256, TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256).
	CipherSuites []uint16

	// ServerName indicates the name of the server requested by the client
	// in order to support virtual hosting. ServerName is only set if the
	// client is using SNI (see RFC 4366, Section 3.1).
	ServerName string

	// SupportedCurves lists the key exchange mechanisms supported by the
	// client. It was renamed to "supported groups" in TLS 1.3, see RFC 8446,
	// Section 4.2.7 and [CurveID].
	//
	// SupportedCurves may be nil in TLS 1.2 and lower if the Supported Elliptic
	// Curves Extension is not being used (see RFC 4492, Section 5.1.1).
	SupportedCurves []CurveID

	// SupportedPoints lists the point formats supported by the client.
	// SupportedPoints is set only if the Supported Point Formats Extension
	// is being used (see RFC 4492, Section 5.1.2).
	SupportedPoints []uint8

	// SignatureSchemes lists the signature and hash schemes that the client
	// is willing to verify. SignatureSchemes is set only if the Signature
	// Algorithms Extension is being used (see RFC 5246, Section 7.4.1.4.1).
	SignatureSchemes []SignatureScheme

	// SupportedProtos lists the application protocols supported by the client.
	// SupportedProtos is set only if the Application-Layer Protocol
	// Negotiation Extension is being used (see RFC 7301, Section 3.1).
	//
	// Servers can select a protocol by setting Config.NextProtos in a
	// GetConfigForClient return value.
	SupportedProtos []string

	// SupportedVersions lists the TLS versions supported by the client.
	// For TLS versions less than 1.3, this is extrapolated from the max
	// version advertised by the client, so values other than the greatest
	// might be rejected if used.
	SupportedVersions []uint16

	// Extensions lists the IDs of the extensions presented by the client
	// in the ClientHello.
	Extensions []uint16

	// Conn is the underlying net.Conn for the connection. Do not read
	// from, or write to, this connection; that will cause the TLS
	// connection to fail.
	Conn net.Conn

	// HelloRetryRequest indicates whether the ClientHello was sent in response
	// to a HelloRetryRequest message.
	HelloRetryRequest bool

	// Ext is what tlsx adds from the ClientHello (x_config.go).
	Ext HelloExt
	// contains filtered or unexported fields
}

type ClientSessionCache interface {
	// Get searches for a ClientSessionState associated with the given key.
	// On return, ok is true if one was found.
	Get(sessionKey string) (session *ClientSessionState, ok bool)

	// Put adds the ClientSessionState to the cache with the given key. It might
	// get called multiple times in a connection if a TLS 1.3 server provides
	// more than one session ticket. If called with a nil *ClientSessionState,
	// it should remove the cache entry.
	Put(sessionKey string, cs *ClientSessionState)
}

type ClientSessionState struct {
	// contains filtered or unexported fields
}

type Config struct {
	// Rand provides the source of entropy for the connection.
	// If Rand is nil, TLS uses the cryptographic random reader in package
	// crypto/rand. The Reader must be safe for use by multiple goroutines.
	//
	// Deprecated: this should be left nil in production. Not all TLS
	// configurations are guaranteed to use Rand. Test code can use
	// [testing/cryptotest.SetGlobalRandom] instead.
	Rand io.Reader

	// Time returns the current time as the number of seconds since the epoch.
	// If Time is nil, TLS uses time.Now.
	Time func() time.Time

	// Certificates contains one or more certificate chains to present to the
	// other side of the connection. The first certificate compatible with the
	// peer's requirements is selected automatically.
	//
	// Server configurations must set one of Certificates, GetCertificate or
	// GetConfigForClient. Clients doing client-authentication may set either
	// Certificates or GetClientCertificate.
	//
	// Note: if there are multiple Certificates, and they don't have the
	// optional field Leaf set, certificate selection will incur a significant
	// per-handshake performance cost.
	Certificates []Certificate

	// NameToCertificate maps from a certificate name to an element of
	// Certificates. Note that a certificate name can be of the form
	// '*.example.com' and so doesn't have to be a domain name as such.
	//
	// Deprecated: NameToCertificate only allows associating a single
	// certificate with a given name. Leave this field nil to let the library
	// select the first compatible chain from Certificates.
	NameToCertificate map[string]*Certificate

	// GetCertificate returns a Certificate based on the given
	// ClientHelloInfo. It will only be called if the client supplies SNI
	// information or if Certificates is empty.
	//
	// If GetCertificate is nil or returns nil, then the certificate is
	// retrieved from NameToCertificate. If NameToCertificate is nil, the
	// best element of Certificates will be used.
	//
	// Once a Certificate is returned it should not be modified.
	GetCertificate func(*ClientHelloInfo) (*Certificate, error)

	// GetClientCertificate, if not nil, is called when a server requests a
	// certificate from a client. If set, the contents of Certificates will
	// be ignored.
	//
	// If GetClientCertificate returns an error, the handshake will be
	// aborted and that error will be returned. Otherwise
	// GetClientCertificate must return a non-nil Certificate. If
	// Certificate.Certificate is empty then no certificate will be sent to
	// the server. If this is unacceptable to the server then it may abort
	// the handshake.
	//
	// GetClientCertificate may be called multiple times for the same
	// connection if renegotiation occurs or if TLS 1.3 is in use.
	//
	// Once a Certificate is returned it should not be modified.
	GetClientCertificate func(*CertificateRequestInfo) (*Certificate, error)

	// GetConfigForClient, if not nil, is called after a ClientHello is
	// received from a client. It may return a non-nil Config in order to
	// change the Config that will be used to handle this connection. If
	// the returned Config is nil, the original Config will be used. The
	// Config returned by this callback may not be subsequently modified.
	//
	// If GetConfigForClient is nil, the Config passed to Server() will be
	// used for all connections.
	//
	// If SessionTicketKey is explicitly set on the returned Config, or if
	// SetSessionTicketKeys is called on the returned Config, those keys will
	// be used. Otherwise, the original Config keys will be used (and possibly
	// rotated if they are automatically managed). WARNING: this allows session
	// resumption of connections originally established with the parent (or a
	// sibling) Config, which may bypass the [Config.VerifyPeerCertificate]
	// value of the returned Config.
	GetConfigForClient func(*ClientHelloInfo) (*Config, error)

	// VerifyPeerCertificate, if not nil, is called after normal
	// certificate verification by either a TLS client or server. It
	// receives the raw ASN.1 certificates provided by the peer and also
	// any verified chains that normal processing found. If it returns a
	// non-nil error, the handshake is aborted and that error results.
	//
	// If normal verification fails then the handshake will abort before
	// considering this callback. If normal verification is disabled (on the
	// client when InsecureSkipVerify is set, or on a server when ClientAuth is
	// RequestClientCert or RequireAnyClientCert), then this callback will be
	// considered but the verifiedChains argument will always be nil. When
	// ClientAuth is NoClientCert, this callback is not called on the server.
	// rawCerts may be empty on the server if ClientAuth is RequestClientCert or
	// VerifyClientCertIfGiven.
	//
	// This callback is not invoked on resumed connections. WARNING: this
	// includes connections resumed across Configs returned by [Config.Clone] or
	// [Config.GetConfigForClient] and their parents. If that is not intended,
	// use [Config.VerifyConnection] instead, or set [Config.SessionTicketsDisabled].
	//
	// verifiedChains and its contents should not be modified.
	VerifyPeerCertificate func(rawCerts [][]byte, verifiedChains [][]*x509.Certificate) error

	// VerifyConnection, if not nil, is called after normal certificate
	// verification and after VerifyPeerCertificate by either a TLS client
	// or server. If it returns a non-nil error, the handshake is aborted
	// and that error results.
	//
	// If normal verification fails then the handshake will abort before
	// considering this callback. This callback will run for all connections,
	// including resumptions, regardless of InsecureSkipVerify or ClientAuth
	// settings.
	VerifyConnection func(ConnectionState) error

	// RootCAs defines the set of root certificate authorities
	// that clients use when verifying server certificates.
	// If RootCAs is nil, TLS uses the host's root CA set.
	RootCAs *x509.CertPool

	// NextProtos is a list of supported application level protocols, in
	// order of preference. If both peers support ALPN, the selected
	// protocol will be one from this list, and the connection will fail
	// if there is no mutually supported protocol. If NextProtos is empty
	// or the peer doesn't support ALPN, the connection will succeed and
	// ConnectionState.NegotiatedProtocol will be empty.
	NextProtos []string

	// ServerName is used to verify the hostname on the returned
	// certificates unless InsecureSkipVerify is given. It is also included
	// in the client's handshake to support virtual hosting unless it is
	// an IP address.
	ServerName string

	// ClientAuth determines the server's policy for
	// TLS Client Authentication. The default is NoClientCert.
	ClientAuth ClientAuthType

	// ClientCAs defines the set of root certificate authorities
	// that servers use if required to verify a client certificate
	// by the policy in ClientAuth.
	ClientCAs *x509.CertPool

	// InsecureSkipVerify controls whether a client verifies the server's
	// certificate chain and host name. If InsecureSkipVerify is true, crypto/tls
	// accepts any certificate presented by the server and any host name in that
	// certificate. In this mode, TLS is susceptible to machine-in-the-middle
	// attacks unless custom verification is used. This should be used only for
	// testing or in combination with VerifyConnection or VerifyPeerCertificate.
	InsecureSkipVerify bool

	// CipherSuites is a list of enabled TLS 1.0–1.2 cipher suites. The order of
	// the list is ignored. Note that TLS 1.3 ciphersuites are not configurable.
	//
	// If CipherSuites is nil, a safe default list is used. The default cipher
	// suites might change over time.
	CipherSuites []uint16

	// PreferServerCipherSuites is a legacy field and has no effect.
	//
	// It used to control whether the server would follow the client's or the
	// server's preference. Servers now select the best mutually supported
	// cipher suite based on logic that takes into account inferred client
	// hardware, server hardware, and security.
	//
	// Deprecated: PreferServerCipherSuites is ignored.
	PreferServerCipherSuites bool

	// SessionTicketsDisabled may be set to true to disable session ticket and
	// PSK (resumption) support. Note that on clients, session ticket support is
	// also disabled if ClientSessionCache is nil.
	SessionTicketsDisabled bool

	// SessionTicketKey is used by TLS servers to provide session resumption.
	// See RFC 5077 and the PSK mode of RFC 8446. If zero, it will be filled
	// with random data before the first server handshake.
	//
	// Deprecated: if this field is left at zero, session ticket keys will be
	// automatically rotated every day and dropped after seven days. For
	// customizing the rotation schedule or synchronizing servers that are
	// terminating connections for the same host, use SetSessionTicketKeys.
	SessionTicketKey [32]byte

	// ClientSessionCache is a cache of ClientSessionState entries for TLS
	// session resumption. It is only used by clients.
	ClientSessionCache ClientSessionCache

	// UnwrapSession is called on the server to turn a ticket/identity
	// previously produced by [WrapSession] into a usable session.
	//
	// UnwrapSession will usually either decrypt a session state in the ticket
	// (for example with [Config.EncryptTicket]), or use the ticket as a handle
	// to recover a previously stored state. It must use [ParseSessionState] to
	// deserialize the session state.
	//
	// If UnwrapSession returns an error, the connection is terminated. If it
	// returns (nil, nil), the session is ignored. crypto/tls may still choose
	// not to resume the returned session.
	UnwrapSession func(identity []byte, cs ConnectionState) (*SessionState, error)

	// WrapSession is called on the server to produce a session ticket/identity.
	//
	// WrapSession must serialize the session state with [SessionState.Bytes].
	// It may then encrypt the serialized state (for example with
	// [Config.DecryptTicket]) and use it as the ticket, or store the state and
	// return a handle for it.
	//
	// If WrapSession returns an error, the connection is terminated.
	//
	// Warning: the return value will be exposed on the wire and to clients in
	// plaintext. The application is in charge of encrypting and authenticating
	// it (and rotating keys) or returning high-entropy identifiers. Failing to
	// do so correctly can compromise current, previous, and future connections
	// depending on the protocol version.
	WrapSession func(ConnectionState, *SessionState) ([]byte, error)

	// MinVersion contains the minimum TLS version that is acceptable.
	//
	// By default, TLS 1.2 is currently used as the minimum. TLS 1.0 is the
	// minimum supported by this package.
	MinVersion uint16

	// MaxVersion contains the maximum TLS version that is acceptable.
	//
	// By default, the maximum version supported by this package is used,
	// which is currently TLS 1.3.
	MaxVersion uint16

	// CurvePreferences contains a set of supported key exchange mechanisms.
	// The name refers to elliptic curves for legacy reasons, see [CurveID].
	// The order of the list is ignored, and key exchange mechanisms are chosen
	// from this list using an internal preference order. If empty, the default
	// will be used.
	//
	// From Go 1.24, the default includes the [X25519MLKEM768] hybrid
	// post-quantum key exchange. To disable it, set CurvePreferences explicitly
	// or use the GODEBUG=tlsmlkem=0 environment variable.
	//
	// From Go 1.26, the default includes the [SecP256r1MLKEM768] and
	// [SecP384r1MLKEM1024] hybrid post-quantum key exchanges, too. To disable
	// them, set CurvePreferences explicitly or use either the
	// GODEBUG=tlsmlkem=0 or the GODEBUG=tlssecpmlkem=0 environment variable.
	CurvePreferences []CurveID

	// DynamicRecordSizingDisabled disables adaptive sizing of TLS records.
	// When true, the largest possible TLS record size is always used. When
	// false, the size of TLS records may be adjusted in an attempt to
	// improve latency.
	DynamicRecordSizingDisabled bool

	// Renegotiation controls what types of renegotiation are supported.
	// The default, none, is correct for the vast majority of applications.
	Renegotiation RenegotiationSupport

	// KeyLogWriter optionally specifies a destination for TLS master secrets
	// in NSS key log format that can be used to allow external programs
	// such as Wireshark to decrypt TLS connections.
	// See https://datatracker.ietf.org/doc/draft-ietf-tls-keylogfile/.
	// Use of KeyLogWriter compromises security and should only be
	// used for debugging.
	KeyLogWriter io.Writer

	// EncryptedClientHelloConfigList is a serialized ECHConfigList. If
	// provided, clients will attempt to connect to servers using Encrypted
	// Client Hello (ECH) using one of the provided ECHConfigs.
	//
	// Servers do not use this field. In order to configure ECH for servers, see
	// the EncryptedClientHelloKeys field.
	//
	// If the list contains no valid ECH configs, the handshake will fail
	// and return an error.
	//
	// If EncryptedClientHelloConfigList is set, MinVersion, if set, must
	// be VersionTLS13.
	//
	// When EncryptedClientHelloConfigList is set, the handshake will only
	// succeed if ECH is successfully negotiated. If the server rejects ECH,
	// an ECHRejectionError error will be returned, which may contain a new
	// ECHConfigList that the server suggests using.
	//
	// How this field is parsed may change in future Go versions, if the
	// encoding described in the final Encrypted Client Hello RFC changes.
	EncryptedClientHelloConfigList []byte

	// EncryptedClientHelloRejectionVerify, if not nil, is called when ECH is
	// rejected by the remote server, in order to verify the ECH provider
	// certificate in the outer ClientHello. If it returns a non-nil error, the
	// handshake is aborted and that error results.
	//
	// On the server side this field is not used.
	//
	// Unlike VerifyPeerCertificate and VerifyConnection, normal certificate
	// verification will not be performed before calling
	// EncryptedClientHelloRejectionVerify.
	//
	// If EncryptedClientHelloRejectionVerify is nil and ECH is rejected, the
	// roots in RootCAs will be used to verify the ECH providers public
	// certificate. VerifyPeerCertificate and VerifyConnection are not called
	// when ECH is rejected, even if set, and InsecureSkipVerify is ignored.
	EncryptedClientHelloRejectionVerify func(ConnectionState) error

	// GetEncryptedClientHelloKeys, if not nil, is called when by a server when
	// a client attempts ECH.
	//
	// If GetEncryptedClientHelloKeys is not nil, [EncryptedClientHelloKeys] is
	// ignored.
	//
	// If GetEncryptedClientHelloKeys returns an error, the handshake will be
	// aborted and the error will be returned. Otherwise,
	// GetEncryptedClientHelloKeys must return a non-nil slice of
	// [EncryptedClientHelloKey] that represents the acceptable ECH keys.
	//
	// For further details, see [EncryptedClientHelloKeys].
	GetEncryptedClientHelloKeys func(*ClientHelloInfo) ([]EncryptedClientHelloKey, error)

	// EncryptedClientHelloKeys are the ECH keys to use when a client
	// attempts ECH.
	//
	// If EncryptedClientHelloKeys is set, MinVersion, if set, must be
	// VersionTLS13.
	//
	// If a client attempts ECH, but it is rejected by the server, the server
	// will send a list of configs to retry based on the set of
	// EncryptedClientHelloKeys which have the SendAsRetry field set.
	//
	// If GetEncryptedClientHelloKeys is non-nil, EncryptedClientHelloKeys is
	// ignored.
	//
	// On the client side, this field is ignored. In order to configure ECH for
	// clients, see the EncryptedClientHelloConfigList field.
	EncryptedClientHelloKeys []EncryptedClientHelloKey

	// Ext holds the tlsx settings (x_config.go).
	Ext ConfigExt
	// contains filtered or unexported fields
}

type ConfigExt struct {
	// AcceptRenegotiation lets a TLS 1.2 server answer a renegotiation the
	// client starts. Off by default; a renegotiation the server itself
	// asked for (Conn.RequestRenegotiation) is always answered. Only secure
	// renegotiation (RFC 5746) is ever performed.
	AcceptRenegotiation bool

	// EncryptThenMAC offers (client) and accepts (server)
	// encrypt_then_mac (RFC 7366) for the TLS 1.2 CBC cipher suites.
	EncryptThenMAC bool
	// RequireEncryptThenMAC (implies EncryptThenMAC) refuses a CBC suite
	// without encrypt_then_mac: a client aborts if the server selects one
	// without echoing it, a server does not select one for a client that
	// did not offer it.
	RequireEncryptThenMAC bool

	// SignatureSchemes, if set, replaces the signature_algorithms list this
	// side sends (ClientHello, CertificateRequest) and accepts; the
	// signature_algorithms_cert list gets them added. It is how
	// rsa_pss_pss_* and the brainpool TLS 1.3 schemes are offered.
	SignatureSchemes []SignatureScheme

	// MaxFragmentLength is the client's max_fragment_length request (RFC
	// 6066 4): 1 to 4 for 512, 1024, 2048 or 4096 bytes; 0 asks nothing. A
	// server always honours a client's request.
	MaxFragmentLength uint8

	// RequestOCSPMulti makes a client also send status_request_v2 (RFC
	// 6961) asking for ocsp_multi, so a TLS 1.2 server can staple OCSP
	// responses for the whole chain.
	RequestOCSPMulti bool

	// TrustedCAKeys are sent by a client in trusted_ca_keys (RFC 6066 6).
	TrustedCAKeys []TrustedAuthority

	// CertificateAuthorities are DER distinguished names a client sends in
	// certificate_authorities (RFC 8446 4.2.4) when it offers TLS 1.3.
	CertificateAuthorities [][]byte

	// ServerSessionCache enables TLS 1.2 resumption by session ID on a
	// server (session tickets work as upstream).
	ServerSessionCache ServerSessionCache
	// ClientSessionIDs makes a TLS 1.2 client keep sessions the server
	// gave a session ID (and no ticket) in Config.ClientSessionCache and
	// offer the ID to resume.
	ClientSessionIDs bool

	// CipherSuitesTLS13, if set, are the TLS 1.3 cipher suites offered (a
	// client) or accepted in this preference order (a server); it allows
	// TLS_AES_128_CCM_SHA256, which is not offered by default.
	CipherSuitesTLS13 []uint16

	// StaticDHCertificate is a server's certificate with a static DH key
	// (PrivateKey *DHPrivateKey), used when the client selects
	// TLS_DH_RSA_WITH_AES_128_GCM_SHA256 (which Config.CipherSuites must
	// list; off by default).
	StaticDHCertificate *Certificate

	// AttributeCertificates are X.509 attribute certificates (DER) this
	// side sends in a SupplementalData message when the peer accepts them
	// (RFC 5878 x509_attr_cert, TLS 1.2 full handshakes); none by default.
	AttributeCertificates [][]byte
	// AcceptAttributeCertificates offers to receive the peer's attribute
	// certificates (ConnectionState().Ext.PeerAttributeCertificates).
	AcceptAttributeCertificates bool

	// AllowSHA1Signatures allows SHA-1 signatures (RSA PKCS #1 v1.5 and
	// ECDSA with SHA-1) in TLS 1.2 handshakes for this Config, as GODEBUG
	// tlssha1=1 does for the whole process: they are offered last, accepted
	// from the peer, and made when the peer prefers them or accepts nothing
	// else (also when a TLS 1.2 peer sends no signature_algorithms). It can
	// only allow: false follows GODEBUG. TLS 1.3 never uses SHA-1
	// signatures. ConnectionState().Ext.SHA1Signature reports their use.
	// CertificateRequestInfo.SupportsCertificate, which has no Config,
	// follows GODEBUG only.
	AllowSHA1Signatures bool

	// PSK configures pre-shared keys: TLS 1.2 PSK suites and TLS 1.3
	// external PSKs (x_psk.go). Nil: none.
	PSK *PSKConfig

	// RawPublicKeys configures raw public keys (RFC 7250; x_rpk.go). Nil:
	// X.509 only.
	RawPublicKeys *RawPublicKeyConfig

	// MinKeyUpdateInterval, if positive, lets a TLS 1.3 peer update its
	// keys on a timer over an idle connection.
	//
	// crypto/tls closes a connection with "too many non-advancing records"
	// after more than 16 post-handshake messages in a row with no
	// application data between them, and since Go 1.26.6 a KeyUpdate no
	// longer resets that count: otherwise a peer could make the other side
	// derive keys without limit. A peer that renews its keys every few
	// minutes on a link that carries no data, as IEC 62351-3 profiles do,
	// is then dropped at its 17th update.
	//
	// With MinKeyUpdateInterval set, a received KeyUpdate that arrives at
	// least this long after the previous one that counted (or after the
	// handshake, for the first) counts as progress: it is not added to
	// that count. A KeyUpdate that arrives sooner counts as upstream does,
	// so a flood is still cut off at the same limit, and the number of
	// key derivations stays bounded by one per interval plus 16. The
	// count is not reset, as application data resets it: other ignored
	// messages and fast updates still add up. Times are taken from
	// Config.Time when a record is read, so the connection must be read
	// while the peer is idle; updates buffered while no one reads arrive
	// together and only the first of them counts as progress.
	//
	// Choose it from the peer's renewal period with a margin for clock
	// drift and network delay (for example half the period); a very
	// short interval gives back most of the protection. Zero, the
	// default, behaves exactly as crypto/tls.
	MinKeyUpdateInterval time.Duration

	// Observer, if set, is told about key updates and renegotiations. It
	// runs on the goroutine doing the work, with connection locks held: it
	// must return quickly and must not call methods of the Conn.
	Observer func(c *Conn, e Event)
}

type Conn struct {
	// contains filtered or unexported fields
}

type ConnectionState struct {
	// Version is the TLS version used by the connection (e.g. VersionTLS12).
	Version uint16

	// HandshakeComplete is true if the handshake has concluded.
	HandshakeComplete bool

	// DidResume is true if this connection was successfully resumed from a
	// previous session with a session ticket or similar mechanism.
	DidResume bool

	// CipherSuite is the cipher suite negotiated for the connection (e.g.
	// TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, TLS_AES_128_GCM_SHA256).
	CipherSuite uint16

	// CurveID is the key exchange mechanism used for the connection. The name
	// refers to elliptic curves for legacy reasons, see [CurveID]. If a legacy
	// RSA key exchange is used, this value is zero.
	CurveID CurveID

	// NegotiatedProtocol is the application protocol negotiated with ALPN.
	NegotiatedProtocol string

	// NegotiatedProtocolIsMutual used to indicate a mutual NPN negotiation.
	//
	// Deprecated: this value is always true.
	NegotiatedProtocolIsMutual bool

	// ServerName is the value of the Server Name Indication extension sent by
	// the client. It's available both on the server and on the client side.
	ServerName string

	// PeerCertificates are the parsed certificates sent by the peer, in the
	// order in which they were sent. The first element is the leaf certificate
	// that the connection is verified against.
	//
	// On the client side, it can't be empty. On the server side, it can be
	// empty if Config.ClientAuth is not RequireAnyClientCert or
	// RequireAndVerifyClientCert.
	//
	// PeerCertificates and its contents should not be modified.
	PeerCertificates []*x509.Certificate

	// VerifiedChains is a list of one or more chains where the first element is
	// PeerCertificates[0] and the last element is from Config.RootCAs (on the
	// client side) or Config.ClientCAs (on the server side).
	//
	// On the client side, it's set if Config.InsecureSkipVerify is false. On
	// the server side, it's set if Config.ClientAuth is VerifyClientCertIfGiven
	// (and the peer provided a certificate) or RequireAndVerifyClientCert.
	//
	// VerifiedChains and its contents should not be modified.
	VerifiedChains [][]*x509.Certificate

	// SignedCertificateTimestamps is a list of SCTs provided by the peer
	// through the TLS handshake for the leaf certificate, if any.
	SignedCertificateTimestamps [][]byte

	// OCSPResponse is a stapled Online Certificate Status Protocol (OCSP)
	// response provided by the peer for the leaf certificate, if any.
	OCSPResponse []byte

	// TLSUnique contains the "tls-unique" channel binding value (see RFC 5929,
	// Section 3). This value will be nil for TLS 1.3 connections and for
	// resumed connections that don't support Extended Master Secret (RFC 7627).
	TLSUnique []byte

	// ECHAccepted indicates if Encrypted Client Hello was offered by the client
	// and accepted by the server. Currently, ECH is supported only on the
	// client side.
	ECHAccepted bool

	// HelloRetryRequest indicates whether we sent a HelloRetryRequest if we
	// are a server, or if we received a HelloRetryRequest if we are a client.
	HelloRetryRequest bool

	// LocalCertificate is the certificate chain presented to the peer, if any,
	// during the handshake. This field is only populated for connections which
	// are not resumed (DidResume is false).
	LocalCertificate [][]byte

	// Ext is the state tlsx adds (x_config.go).
	Ext StateExt
	// contains filtered or unexported fields
}

type CurveID uint16

type DHPrivateKey struct {
	DHPublicKey
	X *big.Int
}

type DHPublicKey struct {
	P, G, Q, Y *big.Int
}

type Dialer struct {
	// NetDialer is the optional dialer to use for the TLS connections'
	// underlying TCP connections.
	// A nil NetDialer is equivalent to the net.Dialer zero value.
	NetDialer *net.Dialer

	// Config is the TLS configuration to use for new connections.
	// A nil configuration is equivalent to the zero
	// configuration; see the documentation of Config for the
	// defaults.
	Config *Config
}

type ECHRejectionError struct {
	RetryConfigList []byte
}

type EncryptedClientHelloKey struct {
	// Config should be a marshalled ECHConfig associated with PrivateKey. This
	// must match the config provided to clients byte-for-byte. The config must
	// use as KEM one of
	//
	//   - DHKEM(P-256, HKDF-SHA256) (0x0010)
	//   - DHKEM(P-384, HKDF-SHA384) (0x0011)
	//   - DHKEM(P-521, HKDF-SHA512) (0x0012)
	//   - DHKEM(X25519, HKDF-SHA256) (0x0020)
	//   - ML-KEM-768 (0x0041)
	//   - ML-KEM-1024 (0x0042)
	//   - MLKEM768-P256 (0x0050)
	//   - MLKEM1024-P384 (0x0051)
	//   - MLKEM768-X25519 (0x647a)
	//
	// and as KDF one of
	//
	//   - HKDF-SHA256 (0x0001)
	//   - HKDF-SHA384 (0x0002)
	//   - HKDF-SHA512 (0x0003)
	//
	// and as AEAD one of
	//
	//   - AES-128-GCM (0x0001)
	//   - AES-256-GCM (0x0002)
	//   - ChaCha20Poly1305 (0x0003)
	//
	Config []byte
	// PrivateKey should be a marshalled private key, in the format expected by
	// HPKE's DeserializePrivateKey (see RFC 9180), for the KEM used in Config.
	PrivateKey []byte
	// SendAsRetry indicates if Config should be sent as part of the list of
	// retry configs when ECH is requested by the client but rejected by the
	// server.
	SendAsRetry bool
}

type Event struct {
	Kind      EventKind
	Requested bool
	ByPeer    bool
	Resumed   bool
	// Version is the negotiated version; PeerVersion is the version the
	// peer asked for when it differs (ErrRenegotiationVersionChange).
	Version, PeerVersion uint16
	Err                  error
}

type EventKind int

type HelloExt struct {
	// PSKModes are the psk_key_exchange_modes offered (0 psk_ke, 1
	// psk_dhe_ke).
	PSKModes []uint8
	// TrustedCAKeys is the client's trusted_ca_keys list, if sent.
	TrustedCAKeys []TrustedAuthority
	// CertificateAuthorities is the client's certificate_authorities.
	CertificateAuthorities [][]byte
	// EncryptThenMAC says the client offered encrypt_then_mac.
	EncryptThenMAC bool
	// MaxFragmentLength is the client's max_fragment_length code (0: none).
	MaxFragmentLength uint8
	// StatusRequestV2 says the client sent status_request_v2.
	StatusRequestV2 bool
	// SecureRenegotiation says the client signalled RFC 5746 support
	// (renegotiation_info or the SCSV).
	SecureRenegotiation bool
	// Renegotiation says the ClientHello starts a renegotiation.
	Renegotiation bool
}

type PSKConfig struct {
	// Identity and Key are what a client offers: the psk_identity of TLS
	// 1.2 and the external identity of TLS 1.3.
	Identity, Key []byte
	// ClientKey, if set, chooses a TLS 1.2 client's identity and key from
	// the server's psk_identity_hint (empty when none was sent); it takes
	// precedence over Identity and Key there.
	ClientKey func(hint []byte) (identity, key []byte, err error)

	// Hint is a TLS 1.2 server's psk_identity_hint (none when empty).
	Hint []byte
	// Lookup gives a server the key of an identity: nil (and no error)
	// for an identity it does not know. It runs in the handshake with the
	// handshake's context and must be safe for concurrent use.
	Lookup func(ctx context.Context, identity []byte) (key []byte, err error)

	// TLS13 offers (client) and accepts (server) the PSK as an external
	// PSK in TLS 1.3. Off: TLS 1.3 handshakes use certificates as usual.
	TLS13 bool
	// Hash is the TLS 1.3 PSK's hash, crypto.SHA256 (the default) or
	// crypto.SHA384; only TLS 1.3 suites with that hash can use it.
	Hash crypto.Hash
	// Resumption allows the sessions of PSK handshakes to be resumed: TLS
	// 1.2 PSK sessions by session ticket as upstream, or by session ID with
	// Config.Ext.ServerSessionCache and ClientSessionIDs; with TLS13, TLS
	// 1.3 sessions of external-PSK handshakes by NewSessionTicket and the
	// resumption PSK (RFC 8446 4.6.1). A session stays bound to its PSK:
	// before resuming it, a server calls Lookup and a client uses Identity
	// and Key (TLS 1.2: or ClientKey, with the hint of the session's full
	// handshake), and the session is resumed only if the identity still has
	// the same key, so removing or changing a key ends resumption of its
	// sessions. A TLS 1.3 client offers the ticket first and its external
	// identity second (not with ECH), so a server that cannot resume the
	// ticket can fall back to the external PSK; a server tries tickets
	// first. psk_ke follows AllowNoDHE and PreferNoDHE on resumption too.
	// Off: every PSK handshake is a full one, and no tickets are sent.
	Resumption bool

	// AllowNoDHE allows TLS 1.3 psk_ke, a key exchange without (EC)DHE
	// and so without forward secrecy. A client then offers both modes; a
	// server uses psk_ke only when the client offers nothing else or
	// PreferNoDHE is set.
	AllowNoDHE, PreferNoDHE bool
}

type QUICConfig struct {
	TLSConfig *Config

	// EnableSessionEvents may be set to true to enable the
	// [QUICStoreSession] and [QUICResumeSession] events for client connections.
	// When this event is enabled, sessions are not automatically
	// stored in the client session cache.
	// The application should use [QUICConn.StoreSession] to store sessions.
	EnableSessionEvents bool

	// ClientHelloInfoConn is the net.Conn to use for the ClientHelloInfo.Conn field.
	ClientHelloInfoConn net.Conn
}

type QUICConn struct {
	// contains filtered or unexported fields
}

type QUICEncryptionLevel int

type QUICEvent struct {
	Kind QUICEventKind

	// Set for QUICSetReadSecret, QUICSetWriteSecret, and QUICWriteData.
	Level QUICEncryptionLevel

	// Set for QUICTransportParameters, QUICSetReadSecret, QUICSetWriteSecret, and QUICWriteData.
	// The contents are owned by crypto/tls, and are valid until the next NextEvent call.
	Data []byte

	// Set for QUICSetReadSecret and QUICSetWriteSecret.
	Suite uint16

	// Set for QUICResumeSession and QUICStoreSession.
	SessionState *SessionState

	// Set for QUICErrorEvent.
	// The error will wrap AlertError.
	Err error
}

type QUICEventKind int

type QUICSessionTicketOptions struct {
	// EarlyData specifies whether the ticket may be used for 0-RTT.
	EarlyData bool
	Extra     [][]byte
}

type RawPublicKeyConfig struct {
	// Send authenticates this side with the public key of its certificate's
	// private key as a raw public key when the peer accepts one. The
	// Certificate may then have no X.509 chain (PrivateKey only); with a
	// chain, X.509 remains the choice for a peer that does not accept raw
	// keys.
	Send bool
	// Verify accepts the peer's raw public key (DER SubjectPublicKeyInfo),
	// typically against a pinned set; a nil error accepts it. Nil: raw keys
	// from the peer are not accepted.
	Verify func(spki []byte) error
	// RawOnly refuses X.509 certificates from the peer.
	RawOnly bool
}

type RecordHeaderError struct {
	// Msg contains a human readable string that describes the error.
	Msg string
	// RecordHeader contains the five bytes of TLS record header that
	// triggered the error.
	RecordHeader [5]byte
	// Conn provides the underlying net.Conn in the case that a client
	// sent an initial handshake that didn't look like TLS.
	// It is nil if there's already been a handshake or a TLS alert has
	// been written to the connection.
	Conn net.Conn
}

type RenegotiationSupport int

type ServerSessionCache interface {
	Get(sessionID string) (*SessionState, bool)
	Put(sessionID string, s *SessionState)
}

type SessionState struct {

	// Extra is ignored by crypto/tls, but is encoded by [SessionState.Bytes]
	// and parsed by [ParseSessionState].
	//
	// This allows [Config.UnwrapSession]/[Config.WrapSession] and
	// [ClientSessionCache] implementations to store and retrieve additional
	// data alongside this session.
	//
	// To allow different layers in a protocol stack to share this field,
	// applications must only append to it, not replace it, and must use entries
	// that can be recognized even if out of order (for example, by starting
	// with an id and version prefix).
	Extra [][]byte

	// EarlyData indicates whether the ticket can be used for 0-RTT in a QUIC
	// connection. The application may set this to false if it is true to
	// decline to offer 0-RTT even if supported.
	EarlyData bool
	// contains filtered or unexported fields
}

type SignatureScheme uint16

type StateExt struct {
	// EncryptThenMAC says encrypt_then_mac is in use (TLS 1.2 CBC suites).
	EncryptThenMAC bool
	// MaxFragmentLength is the negotiated record plaintext limit in bytes
	// (0: none, 16384).
	MaxFragmentLength int
	// SecureRenegotiation says the peer signalled RFC 5746 support in the
	// first handshake (TLS 1.2).
	SecureRenegotiation bool
	// Handshakes counts completed handshakes on the connection (1 plus
	// renegotiations).
	Handshakes int
	// KeyUpdatesSent and KeyUpdatesReceived count TLS 1.3 KeyUpdate
	// messages.
	KeyUpdatesSent, KeyUpdatesReceived uint64
	// LastKeyUpdateReceived is when the peer last updated its keys.
	LastKeyUpdateReceived time.Time
	// OCSPResponses are the stapled OCSP responses by position in
	// PeerCertificates (nil where none was stapled); OCSPResponse is
	// OCSPResponses[0].
	OCSPResponses [][]byte
	// SessionCreated is, on a TLS 1.2 server connection that resumed a
	// session (ticket or session ID), when the session's full handshake
	// was made (zero otherwise).
	SessionCreated time.Time
	// TrustedCAKeysAcknowledged says the server confirmed it chose its
	// certificate by the client's trusted_ca_keys (RFC 6066 6).
	TrustedCAKeysAcknowledged bool
	// PeerCertificateAuthorities are the DER names the peer sent in
	// certificate_authorities (a client's ClientHello, a server's
	// CertificateRequest).
	PeerCertificateAuthorities [][]byte
	// PeerAttributeCertificates are the attribute certificates the peer
	// sent (RFC 5878), unverified: the application checks them.
	PeerAttributeCertificates [][]byte
	// PSKIdentity is the pre-shared key identity the handshake used (nil
	// when none; empty but not nil for an empty TLS 1.2 identity);
	// PSKIdentityHint the TLS 1.2 server's hint a client got.
	PSKIdentity, PSKIdentityHint []byte
	// SHA1Signature says a TLS 1.2 handshake on the connection used a
	// SHA-1 signature, by either side (Config.Ext.AllowSHA1Signatures,
	// GODEBUG tlssha1=1).
	SHA1Signature bool
	// PeerRawPublicKey is the peer's raw public key (DER
	// SubjectPublicKeyInfo, RFC 7250) when it authenticated with one;
	// PeerCertificates is then empty. OwnRawPublicKey says this side sent
	// a raw public key.
	PeerRawPublicKey []byte
	OwnRawPublicKey  bool
}

type TrustedAuthority struct {
	// Type is 0 pre_agreed, 1 key_sha1_hash, 2 x509_name, 3 cert_sha1_hash.
	Type uint8
	// Data is the SHA-1 hash (types 1 and 3) or the DER distinguished name
	// (type 2); empty for pre_agreed.
	Data []byte
}