Package tls partially implements TLS 1.2, as specified in RFC 5246, and TLS 1.3, as specified in RFC 8446.


type ClientSessionCache

 1type ClientSessionCache interface {
 2	// Get searches for a ClientSessionState associated with the given key.
 3	// On return, ok is true if one was found.
 4	Get(sessionKey string) (session *ClientSessionState, ok bool)
 6	// Put adds the ClientSessionState to the cache with the given key. It might
 7	// get called multiple times in a connection if a TLS 1.3 server provides
 8	// more than one session ticket. If called with a nil *ClientSessionState,
 9	// it should remove the cache entry.
10	Put(sessionKey string, cs *ClientSessionState)

ClientSessionCache is a cache of ClientSessionState objects that can be used by a client to resume a TLS session with a given server. ClientSessionCache implementations should expect to be called concurrently from different goroutines. Up to TLS 1.2, only ticket-based resumption is supported, not SessionID-based resumption. In TLS 1.3 they were merged into PSK modes, which are supported via this interface.

type Config

  1type Config struct {
  2	// Rand provides the source of entropy for nonces and RSA blinding.
  3	// If Rand is nil, TLS uses the cryptographic random reader in package
  4	// crypto/rand.
  5	// The Reader must be safe for use by multiple goroutines.
  6	Rand	io.Reader
  8	// Time returns the current time as the number of seconds since the epoch.
  9	// If Time is nil, TLS uses time.Now.
 10	Time	func() time.Time
 12	// Certificates contains one or more certificate chains to present to the
 13	// other side of the connection. The first certificate compatible with the
 14	// peer's requirements is selected automatically.
 15	//
 16	// Server configurations must set one of Certificates, GetCertificate or
 17	// GetConfigForClient. Clients doing client-authentication may set either
 18	// Certificates or GetClientCertificate.
 19	//
 20	// Note: if there are multiple Certificates, and they don't have the
 21	// optional field Leaf set, certificate selection will incur a significant
 22	// per-handshake performance cost.
 23	Certificates	[]Certificate
 25	// NameToCertificate maps from a certificate name to an element of
 26	// Certificates. Note that a certificate name can be of the form
 27	// '*' and so doesn't have to be a domain name as such.
 28	//
 29	// Deprecated: NameToCertificate only allows associating a single
 30	// certificate with a given name. Leave this field nil to let the library
 31	// select the first compatible chain from Certificates.
 32	NameToCertificate	map[string]*Certificate
 34	// GetCertificate returns a Certificate based on the given
 35	// ClientHelloInfo. It will only be called if the client supplies SNI
 36	// information or if Certificates is empty.
 37	//
 38	// If GetCertificate is nil or returns nil, then the certificate is
 39	// retrieved from NameToCertificate. If NameToCertificate is nil, the
 40	// best element of Certificates will be used.
 41	//
 42	// Once a Certificate is returned it should not be modified.
 43	GetCertificate	func(*ClientHelloInfo) (*Certificate, error)
 45	// GetClientCertificate, if not nil, is called when a server requests a
 46	// certificate from a client. If set, the contents of Certificates will
 47	// be ignored.
 48	//
 49	// If GetClientCertificate returns an error, the handshake will be
 50	// aborted and that error will be returned. Otherwise
 51	// GetClientCertificate must return a non-nil Certificate. If
 52	// Certificate.Certificate is empty then no certificate will be sent to
 53	// the server. If this is unacceptable to the server then it may abort
 54	// the handshake.
 55	//
 56	// GetClientCertificate may be called multiple times for the same
 57	// connection if renegotiation occurs or if TLS 1.3 is in use.
 58	//
 59	// Once a Certificate is returned it should not be modified.
 60	GetClientCertificate	func(*CertificateRequestInfo) (*Certificate, error)
 62	// GetConfigForClient, if not nil, is called after a ClientHello is
 63	// received from a client. It may return a non-nil Config in order to
 64	// change the Config that will be used to handle this connection. If
 65	// the returned Config is nil, the original Config will be used. The
 66	// Config returned by this callback may not be subsequently modified.
 67	//
 68	// If GetConfigForClient is nil, the Config passed to Server() will be
 69	// used for all connections.
 70	//
 71	// If SessionTicketKey was explicitly set on the returned Config, or if
 72	// SetSessionTicketKeys was called on the returned Config, those keys will
 73	// be used. Otherwise, the original Config keys will be used (and possibly
 74	// rotated if they are automatically managed).
 75	GetConfigForClient	func(*ClientHelloInfo) (*Config, error)
 77	// VerifyPeerCertificate, if not nil, is called after normal
 78	// certificate verification by either a TLS client or server. It
 79	// receives the raw ASN.1 certificates provided by the peer and also
 80	// any verified chains that normal processing found. If it returns a
 81	// non-nil error, the handshake is aborted and that error results.
 82	//
 83	// If normal verification fails then the handshake will abort before
 84	// considering this callback. If normal verification is disabled by
 85	// setting InsecureSkipVerify, or (for a server) when ClientAuth is
 86	// RequestClientCert or RequireAnyClientCert, then this callback will
 87	// be considered but the verifiedChains argument will always be nil.
 88	//
 89	// verifiedChains and its contents should not be modified.
 90	VerifyPeerCertificate	func(rawCerts [][]byte, verifiedChains [][]*x509.Certificate) error
 92	// VerifyConnection, if not nil, is called after normal certificate
 93	// verification and after VerifyPeerCertificate by either a TLS client
 94	// or server. If it returns a non-nil error, the handshake is aborted
 95	// and that error results.
 96	//
 97	// If normal verification fails then the handshake will abort before
 98	// considering this callback. This callback will run for all connections
 99	// regardless of InsecureSkipVerify or ClientAuth settings.
100	VerifyConnection	func(ConnectionState) error
102	// RootCAs defines the set of root certificate authorities
103	// that clients use when verifying server certificates.
104	// If RootCAs is nil, TLS uses the host's root CA set.
105	RootCAs	*x509.CertPool
107	// NextProtos is a list of supported application level protocols, in
108	// order of preference. If both peers support ALPN, the selected
109	// protocol will be one from this list, and the connection will fail
110	// if there is no mutually supported protocol. If NextProtos is empty
111	// or the peer doesn't support ALPN, the connection will succeed and
112	// ConnectionState.NegotiatedProtocol will be empty.
113	NextProtos	[]string
115	// ServerName is used to verify the hostname on the returned
116	// certificates unless InsecureSkipVerify is given. It is also included
117	// in the client's handshake to support virtual hosting unless it is
118	// an IP address.
119	ServerName	string
121	// ClientAuth determines the server's policy for
122	// TLS Client Authentication. The default is NoClientCert.
123	ClientAuth	ClientAuthType
125	// ClientCAs defines the set of root certificate authorities
126	// that servers use if required to verify a client certificate
127	// by the policy in ClientAuth.
128	ClientCAs	*x509.CertPool
130	// InsecureSkipVerify controls whether a client verifies the server's
131	// certificate chain and host name. If InsecureSkipVerify is true, crypto/tls
132	// accepts any certificate presented by the server and any host name in that
133	// certificate. In this mode, TLS is susceptible to machine-in-the-middle
134	// attacks unless custom verification is used. This should be used only for
135	// testing or in combination with VerifyConnection or VerifyPeerCertificate.
136	InsecureSkipVerify	bool
138	// CipherSuites is a list of enabled TLS 1.0–1.2 cipher suites. The order of
139	// the list is ignored. Note that TLS 1.3 ciphersuites are not configurable.
140	//
141	// If CipherSuites is nil, a safe default list is used. The default cipher
142	// suites might change over time.
143	CipherSuites	[]uint16
145	// PreferServerCipherSuites is a legacy field and has no effect.
146	//
147	// It used to control whether the server would follow the client's or the
148	// server's preference. Servers now select the best mutually supported
149	// cipher suite based on logic that takes into account inferred client
150	// hardware, server hardware, and security.
151	//
152	// Deprecated: PreferServerCipherSuites is ignored.
153	PreferServerCipherSuites	bool
155	// SessionTicketsDisabled may be set to true to disable session ticket and
156	// PSK (resumption) support. Note that on clients, session ticket support is
157	// also disabled if ClientSessionCache is nil.
158	SessionTicketsDisabled	bool
160	// SessionTicketKey is used by TLS servers to provide session resumption.
161	// See RFC 5077 and the PSK mode of RFC 8446. If zero, it will be filled
162	// with random data before the first server handshake.
163	//
164	// Deprecated: if this field is left at zero, session ticket keys will be
165	// automatically rotated every day and dropped after seven days. For
166	// customizing the rotation schedule or synchronizing servers that are
167	// terminating connections for the same host, use SetSessionTicketKeys.
168	SessionTicketKey	[32]byte
170	// ClientSessionCache is a cache of ClientSessionState entries for TLS
171	// session resumption. It is only used by clients.
172	ClientSessionCache	ClientSessionCache
174	// MinVersion contains the minimum TLS version that is acceptable.
175	//
176	// By default, TLS 1.2 is currently used as the minimum when acting as a
177	// client, and TLS 1.0 when acting as a server. TLS 1.0 is the minimum
178	// supported by this package, both as a client and as a server.
179	//
180	// The client-side default can temporarily be reverted to TLS 1.0 by
181	// including the value "x509sha1=1" in the GODEBUG environment variable.
182	// Note that this option will be removed in Go 1.19 (but it will still be
183	// possible to set this field to VersionTLS10 explicitly).
184	MinVersion	uint16
186	// MaxVersion contains the maximum TLS version that is acceptable.
187	//
188	// By default, the maximum version supported by this package is used,
189	// which is currently TLS 1.3.
190	MaxVersion	uint16
192	// CurvePreferences contains the elliptic curves that will be used in
193	// an ECDHE handshake, in preference order. If empty, the default will
194	// be used. The client will use the first preference as the type for
195	// its key share in TLS 1.3. This may change in the future.
196	CurvePreferences	[]CurveID
198	// DynamicRecordSizingDisabled disables adaptive sizing of TLS records.
199	// When true, the largest possible TLS record size is always used. When
200	// false, the size of TLS records may be adjusted in an attempt to
201	// improve latency.
202	DynamicRecordSizingDisabled	bool
204	// Renegotiation controls what types of renegotiation are supported.
205	// The default, none, is correct for the vast majority of applications.
206	Renegotiation	RenegotiationSupport
208	// KeyLogWriter optionally specifies a destination for TLS master secrets
209	// in NSS key log format that can be used to allow external programs
210	// such as Wireshark to decrypt TLS connections.
211	// See
212	// Use of KeyLogWriter compromises security and should only be
213	// used for debugging.
214	KeyLogWriter	io.Writer

A Config structure is used to configure a TLS client or server. After one has been passed to a TLS function it must not be modified. A Config may be reused; the tls package will also not modify it.

func BuildNameToCertificate

1func (c *Config) BuildNameToCertificate()

BuildNameToCertificate parses c.Certificates and builds c.NameToCertificate from the CommonName and SubjectAlternateName fields of each of the leaf certificates.

Deprecated: NameToCertificate only allows associating a single certificate with a given name. Leave that field nil to let the library select the first compatible chain from Certificates.

func Clone

1func (c *Config) Clone() *Config

Clone returns a shallow clone of c or nil if c is nil. It is safe to clone a Config that is being used concurrently by a TLS client or server.

func SetSessionTicketKeys

1func (c *Config) SetSessionTicketKeys(keys [][32]byte)

SetSessionTicketKeys updates the session ticket keys for a server.

The first key will be used when creating new tickets, while all keys can be used for decrypting tickets. It is safe to call this function while the server is running in order to rotate the session ticket keys. The function will panic if keys is empty.

Calling this function will turn off automatic session ticket key rotation.

If multiple servers are terminating connections for the same host they should all have the same session ticket keys. If the session ticket keys leaks, previously recorded and future TLS connections using those keys might be compromised.

© Matthias Hochgatterer – MastodonGithubRésumé