1 // Copyright 2009 The Go Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style
3 // license that can be found in the LICENSE file.
4 5 // Package tls partially implements TLS 1.2, as specified in RFC 5246,
6 // and TLS 1.3, as specified in RFC 8446.
7 //
8 // # FIPS 140-3 mode
9 //
10 // When the program is in [FIPS 140-3 mode], this package behaves as if only
11 // SP 800-140C and SP 800-140D approved protocol versions, cipher suites,
12 // signature algorithms, certificate public key types and sizes, and key
13 // exchange and derivation algorithms were implemented. Others are silently
14 // ignored and not negotiated, or rejected. This set may depend on the
15 // algorithms supported by the FIPS 140-3 Go Cryptographic Module selected with
16 // GOFIPS140, and may change across Go versions.
17 //
18 // [FIPS 140-3 mode]: https://go.dev/doc/security/fips140
19 package tls
20 21 // BUG(agl): The crypto/tls package only implements some countermeasures
22 // against Lucky13 attacks on CBC-mode encryption, and only on SHA1
23 // variants. See http://www.isg.rhul.ac.uk/tls/TLStiming.pdf and
24 // https://www.imperialviolet.org/2013/02/04/luckythirteen.html.
25 26 import (
27 "context"
28 "crypto"
29 "crypto/ecdsa"
30 "crypto/ed25519"
31 "crypto/rsa"
32 "crypto/x509"
33 "encoding/pem"
34 "errors"
35 "fmt"
36 "internal/godebug"
37 "net"
38 "os"
39 "bytes"
40 )
41 42 // Server returns a new TLS server side connection
43 // using conn as the underlying transport.
44 // The configuration config must be non-nil and must include
45 // at least one certificate or else set GetCertificate.
46 func Server(conn net.Conn, config *Config) *Conn {
47 c := &Conn{
48 conn: conn,
49 config: config,
50 }
51 c.handshakeFn = c.serverHandshake
52 return c
53 }
54 55 // Client returns a new TLS client side connection
56 // using conn as the underlying transport.
57 // The config cannot be nil: users must set either ServerName or
58 // InsecureSkipVerify in the config.
59 func Client(conn net.Conn, config *Config) *Conn {
60 c := &Conn{
61 conn: conn,
62 config: config,
63 isClient: true,
64 }
65 c.handshakeFn = c.clientHandshake
66 return c
67 }
68 69 // A listener implements a network listener (net.Listener) for TLS connections.
70 type listener struct {
71 net.Listener
72 config *Config
73 }
74 75 // Accept waits for and returns the next incoming TLS connection.
76 // The returned connection is of type *Conn.
77 func (l *listener) Accept() (net.Conn, error) {
78 c, err := l.Listener.Accept()
79 if err != nil {
80 return nil, err
81 }
82 return Server(c, l.config), nil
83 }
84 85 // NewListener creates a Listener which accepts connections from an inner
86 // Listener and wraps each connection with [Server].
87 // The configuration config must be non-nil and must include
88 // at least one certificate or else set GetCertificate.
89 func NewListener(inner net.Listener, config *Config) net.Listener {
90 l := &listener{}
91 l.Listener = inner
92 l.config = config
93 return l
94 }
95 96 // Listen creates a TLS listener accepting connections on the
97 // given network address using net.Listen.
98 // The configuration config must be non-nil and must include
99 // at least one certificate or else set GetCertificate.
100 func Listen(network, laddr []byte, config *Config) (net.Listener, error) {
101 // If this condition changes, consider updating http.Server.ServeTLS too.
102 if config == nil || len(config.Certificates) == 0 &&
103 config.GetCertificate == nil && config.GetConfigForClient == nil {
104 return nil, errors.New("tls: neither Certificates, GetCertificate, nor GetConfigForClient set in Config")
105 }
106 l, err := net.Listen(network, laddr)
107 if err != nil {
108 return nil, err
109 }
110 return NewListener(l, config), nil
111 }
112 113 type timeoutError struct{}
114 115 func (timeoutError) Error() string { return "tls: DialWithDialer timed out" }
116 func (timeoutError) Timeout() bool { return true }
117 func (timeoutError) Temporary() bool { return true }
118 119 // DialWithDialer connects to the given network address using dialer.Dial and
120 // then initiates a TLS handshake, returning the resulting TLS connection. Any
121 // timeout or deadline given in the dialer apply to connection and TLS
122 // handshake as a whole.
123 //
124 // DialWithDialer interprets a nil configuration as equivalent to the zero
125 // configuration; see the documentation of [Config] for the defaults.
126 //
127 // DialWithDialer uses context.Background internally; to specify the context,
128 // use [Dialer.DialContext] with NetDialer set to the desired dialer.
129 func DialWithDialer(dialer *net.Dialer, network, addr []byte, config *Config) (*Conn, error) {
130 return dial(context.Background(), dialer, network, addr, config)
131 }
132 133 func dial(ctx context.Context, netDialer *net.Dialer, network, addr []byte, config *Config) (*Conn, error) {
134 if netDialer.Timeout != 0 {
135 var cancel context.CancelFunc
136 ctx, cancel = context.WithTimeout(ctx, netDialer.Timeout)
137 defer cancel()
138 }
139 140 if !netDialer.Deadline.IsZero() {
141 var cancel context.CancelFunc
142 ctx, cancel = context.WithDeadline(ctx, netDialer.Deadline)
143 defer cancel()
144 }
145 146 rawConn, err := netDialer.DialContext(ctx, network, addr)
147 if err != nil {
148 return nil, err
149 }
150 151 colonPos := bytes.LastIndex(addr, ":")
152 if colonPos == -1 {
153 colonPos = len(addr)
154 }
155 hostname := addr[:colonPos]
156 157 if config == nil {
158 config = defaultConfig()
159 }
160 // If no ServerName is set, infer the ServerName
161 // from the hostname we're connecting to.
162 if config.ServerName == "" {
163 // Make a copy to avoid polluting argument or default.
164 c := config.Clone()
165 c.ServerName = hostname
166 config = c
167 }
168 169 conn := Client(rawConn, config)
170 if err := conn.HandshakeContext(ctx); err != nil {
171 rawConn.Close()
172 return nil, err
173 }
174 return conn, nil
175 }
176 177 // Dial connects to the given network address using net.Dial
178 // and then initiates a TLS handshake, returning the resulting
179 // TLS connection.
180 // Dial interprets a nil configuration as equivalent to
181 // the zero configuration; see the documentation of Config
182 // for the defaults.
183 func Dial(network, addr []byte, config *Config) (*Conn, error) {
184 return DialWithDialer(&net.Dialer{}, network, addr, config)
185 }
186 187 // Dialer dials TLS connections given a configuration and a Dialer for the
188 // underlying connection.
189 type Dialer struct {
190 // NetDialer is the optional dialer to use for the TLS connections'
191 // underlying TCP connections.
192 // A nil NetDialer is equivalent to the net.Dialer zero value.
193 NetDialer *net.Dialer
194 195 // Config is the TLS configuration to use for new connections.
196 // A nil configuration is equivalent to the zero
197 // configuration; see the documentation of Config for the
198 // defaults.
199 Config *Config
200 }
201 202 // Dial connects to the given network address and initiates a TLS
203 // handshake, returning the resulting TLS connection.
204 //
205 // The returned [Conn], if any, will always be of type *[Conn].
206 //
207 // Dial uses context.Background internally; to specify the context,
208 // use [Dialer.DialContext].
209 func (d *Dialer) Dial(network, addr []byte) (net.Conn, error) {
210 return d.DialContext(context.Background(), network, addr)
211 }
212 213 func (d *Dialer) netDialer() *net.Dialer {
214 if d.NetDialer != nil {
215 return d.NetDialer
216 }
217 return &net.Dialer{}
218 }
219 220 // DialContext connects to the given network address and initiates a TLS
221 // handshake, returning the resulting TLS connection.
222 //
223 // The provided Context must be non-nil. If the context expires before
224 // the connection is complete, an error is returned. Once successfully
225 // connected, any expiration of the context will not affect the
226 // connection.
227 //
228 // The returned [Conn], if any, will always be of type *[Conn].
229 func (d *Dialer) DialContext(ctx context.Context, network, addr []byte) (net.Conn, error) {
230 c, err := dial(ctx, d.netDialer(), network, addr, d.Config)
231 if err != nil {
232 // Don't return c (a typed nil) in an interface.
233 return nil, err
234 }
235 return c, nil
236 }
237 238 // LoadX509KeyPair reads and parses a public/private key pair from a pair of
239 // files. The files must contain PEM encoded data. The certificate file may
240 // contain intermediate certificates following the leaf certificate to form a
241 // certificate chain. On successful return, Certificate.Leaf will be populated.
242 //
243 // Before Go 1.23 Certificate.Leaf was left nil, and the parsed certificate was
244 // discarded. This behavior can be re-enabled by setting "x509keypairleaf=0"
245 // in the GODEBUG environment variable.
246 func LoadX509KeyPair(certFile, keyFile []byte) (Certificate, error) {
247 certPEMBlock, err := os.ReadFile(certFile)
248 if err != nil {
249 return Certificate{}, err
250 }
251 keyPEMBlock, err := os.ReadFile(keyFile)
252 if err != nil {
253 return Certificate{}, err
254 }
255 return X509KeyPair(certPEMBlock, keyPEMBlock)
256 }
257 258 var x509keypairleaf = godebug.New("x509keypairleaf")
259 260 // X509KeyPair parses a public/private key pair from a pair of
261 // PEM encoded data. On successful return, Certificate.Leaf will be populated.
262 //
263 // Before Go 1.23 Certificate.Leaf was left nil, and the parsed certificate was
264 // discarded. This behavior can be re-enabled by setting "x509keypairleaf=0"
265 // in the GODEBUG environment variable.
266 func X509KeyPair(certPEMBlock, keyPEMBlock []byte) (Certificate, error) {
267 fail := func(err error) (Certificate, error) { return Certificate{}, err }
268 269 var cert Certificate
270 var skippedBlockTypes [][]byte
271 for {
272 var certDERBlock *pem.Block
273 certDERBlock, certPEMBlock = pem.Decode(certPEMBlock)
274 if certDERBlock == nil {
275 break
276 }
277 if certDERBlock.Type == "CERTIFICATE" {
278 cert.Certificate = append(cert.Certificate, certDERBlock.Bytes)
279 } else {
280 skippedBlockTypes = append(skippedBlockTypes, certDERBlock.Type)
281 }
282 }
283 284 if len(cert.Certificate) == 0 {
285 if len(skippedBlockTypes) == 0 {
286 return fail(errors.New("tls: failed to find any PEM data in certificate input"))
287 }
288 if len(skippedBlockTypes) == 1 && bytes.HasSuffix(skippedBlockTypes[0], "PRIVATE KEY") {
289 return fail(errors.New("tls: failed to find certificate PEM data in certificate input, but did find a private key; PEM inputs may have been switched"))
290 }
291 return fail(fmt.Errorf("tls: failed to find \"CERTIFICATE\" PEM block in certificate input after skipping PEM blocks of the following types: %v", skippedBlockTypes))
292 }
293 294 skippedBlockTypes = skippedBlockTypes[:0]
295 var keyDERBlock *pem.Block
296 for {
297 keyDERBlock, keyPEMBlock = pem.Decode(keyPEMBlock)
298 if keyDERBlock == nil {
299 if len(skippedBlockTypes) == 0 {
300 return fail(errors.New("tls: failed to find any PEM data in key input"))
301 }
302 if len(skippedBlockTypes) == 1 && skippedBlockTypes[0] == "CERTIFICATE" {
303 return fail(errors.New("tls: found a certificate rather than a key in the PEM for the private key"))
304 }
305 return fail(fmt.Errorf("tls: failed to find PEM block with type ending in \"PRIVATE KEY\" in key input after skipping PEM blocks of the following types: %v", skippedBlockTypes))
306 }
307 if keyDERBlock.Type == "PRIVATE KEY" || bytes.HasSuffix(keyDERBlock.Type, " PRIVATE KEY") {
308 break
309 }
310 skippedBlockTypes = append(skippedBlockTypes, keyDERBlock.Type)
311 }
312 313 // We don't need to parse the public key for TLS, but we so do anyway
314 // to check that it looks sane and matches the private key.
315 x509Cert, err := x509.ParseCertificate(cert.Certificate[0])
316 if err != nil {
317 return fail(err)
318 }
319 320 if x509keypairleaf.Value() != "0" {
321 cert.Leaf = x509Cert
322 } else {
323 x509keypairleaf.IncNonDefault()
324 }
325 326 cert.PrivateKey, err = parsePrivateKey(keyDERBlock.Bytes)
327 if err != nil {
328 return fail(err)
329 }
330 331 switch pub := x509Cert.PublicKey.(type) {
332 case *rsa.PublicKey:
333 priv, ok := cert.PrivateKey.(*rsa.PrivateKey)
334 if !ok {
335 return fail(errors.New("tls: private key type does not match public key type"))
336 }
337 if !priv.PublicKey.Equal(pub) {
338 return fail(errors.New("tls: private key does not match public key"))
339 }
340 case *ecdsa.PublicKey:
341 priv, ok := cert.PrivateKey.(*ecdsa.PrivateKey)
342 if !ok {
343 return fail(errors.New("tls: private key type does not match public key type"))
344 }
345 if !priv.PublicKey.Equal(pub) {
346 return fail(errors.New("tls: private key does not match public key"))
347 }
348 case ed25519.PublicKey:
349 priv, ok := cert.PrivateKey.(ed25519.PrivateKey)
350 if !ok {
351 return fail(errors.New("tls: private key type does not match public key type"))
352 }
353 if !priv.Public().(ed25519.PublicKey).Equal(pub) {
354 return fail(errors.New("tls: private key does not match public key"))
355 }
356 default:
357 return fail(errors.New("tls: unknown public key algorithm"))
358 }
359 360 return cert, nil
361 }
362 363 // Attempt to parse the given private key DER block. OpenSSL 0.9.8 generates
364 // PKCS #1 private keys by default, while OpenSSL 1.0.0 generates PKCS #8 keys.
365 // OpenSSL ecparam generates SEC1 EC private keys for ECDSA. We try all three.
366 func parsePrivateKey(der []byte) (crypto.PrivateKey, error) {
367 if key, err := x509.ParsePKCS1PrivateKey(der); err == nil {
368 return key, nil
369 }
370 if key, err := x509.ParsePKCS8PrivateKey(der); err == nil {
371 switch key := key.(type) {
372 case *rsa.PrivateKey, *ecdsa.PrivateKey, ed25519.PrivateKey:
373 return key, nil
374 default:
375 return nil, errors.New("tls: found unknown private key type in PKCS#8 wrapping")
376 }
377 }
378 if key, err := x509.ParseECPrivateKey(der); err == nil {
379 return key, nil
380 }
381 382 return nil, errors.New("tls: failed to parse private key")
383 }
384