crypto/tls

 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)
 5
 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)
11}

  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
  7
  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
 11
 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
 24
 25	// NameToCertificate maps from a certificate name to an element of
 26	// Certificates. Note that a certificate name can be of the form
 27	// '*.example.com' 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
 33
 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)
 44
 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)
 61
 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)
 76
 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
 91
 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
101
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
106
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
114
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
120
121	// ClientAuth determines the server's policy for
122	// TLS Client Authentication. The default is NoClientCert.
123	ClientAuth	ClientAuthType
124
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
129
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
137
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
144
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
154
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
159
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
169
170	// ClientSessionCache is a cache of ClientSessionState entries for TLS
171	// session resumption. It is only used by clients.
172	ClientSessionCache	ClientSessionCache
173
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
185
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
191
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
197
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
203
204	// Renegotiation controls what types of renegotiation are supported.
205	// The default, none, is correct for the vast majority of applications.
206	Renegotiation	RenegotiationSupport
207
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 https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Key_Log_Format.
212	// Use of KeyLogWriter compromises security and should only be
213	// used for debugging.
214	KeyLogWriter	io.Writer
215}