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 5package tls 6 7import ( 8 "crypto" 9 "crypto/rand" 10 "crypto/x509" 11 "io" 12 "strings" 13 "sync" 14 "time" 15) 16 17const ( 18 maxPlaintext = 16384 // maximum plaintext payload length 19 maxCiphertext = 16384 + 2048 // maximum ciphertext payload length 20 recordHeaderLen = 5 // record header length 21 maxHandshake = 65536 // maximum handshake we support (protocol max is 16 MB) 22 23 versionSSL30 = 0x0300 24 versionTLS10 = 0x0301 25 26 minVersion = versionSSL30 27 maxVersion = versionTLS10 28) 29 30// TLS record types. 31type recordType uint8 32 33const ( 34 recordTypeChangeCipherSpec recordType = 20 35 recordTypeAlert recordType = 21 36 recordTypeHandshake recordType = 22 37 recordTypeApplicationData recordType = 23 38) 39 40// TLS handshake message types. 41const ( 42 typeClientHello uint8 = 1 43 typeServerHello uint8 = 2 44 typeNewSessionTicket uint8 = 4 45 typeCertificate uint8 = 11 46 typeServerKeyExchange uint8 = 12 47 typeCertificateRequest uint8 = 13 48 typeServerHelloDone uint8 = 14 49 typeCertificateVerify uint8 = 15 50 typeClientKeyExchange uint8 = 16 51 typeFinished uint8 = 20 52 typeCertificateStatus uint8 = 22 53 typeNextProtocol uint8 = 67 // Not IANA assigned 54) 55 56// TLS compression types. 57const ( 58 compressionNone uint8 = 0 59) 60 61// TLS extension numbers 62var ( 63 extensionServerName uint16 = 0 64 extensionStatusRequest uint16 = 5 65 extensionSupportedCurves uint16 = 10 66 extensionSupportedPoints uint16 = 11 67 extensionSessionTicket uint16 = 35 68 extensionNextProtoNeg uint16 = 13172 // not IANA assigned 69) 70 71// TLS Elliptic Curves 72// http://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-8 73var ( 74 curveP256 uint16 = 23 75 curveP384 uint16 = 24 76 curveP521 uint16 = 25 77) 78 79// TLS Elliptic Curve Point Formats 80// http://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-9 81var ( 82 pointFormatUncompressed uint8 = 0 83) 84 85// TLS CertificateStatusType (RFC 3546) 86const ( 87 statusTypeOCSP uint8 = 1 88) 89 90// Certificate types (for certificateRequestMsg) 91const ( 92 certTypeRSASign = 1 // A certificate containing an RSA key 93 certTypeDSSSign = 2 // A certificate containing a DSA key 94 certTypeRSAFixedDH = 3 // A certificate containing a static DH key 95 certTypeDSSFixedDH = 4 // A certificate containing a static DH key 96 // Rest of these are reserved by the TLS spec 97) 98 99// ConnectionState records basic TLS details about the connection. 100type ConnectionState struct { 101 HandshakeComplete bool 102 DidResume bool 103 CipherSuite uint16 104 NegotiatedProtocol string 105 NegotiatedProtocolIsMutual bool 106 107 // ServerName contains the server name indicated by the client, if any. 108 // (Only valid for server connections.) 109 ServerName string 110 111 // the certificate chain that was presented by the other side 112 PeerCertificates []*x509.Certificate 113 // the verified certificate chains built from PeerCertificates. 114 VerifiedChains [][]*x509.Certificate 115} 116 117// ClientAuthType declares the policy the server will follow for 118// TLS Client Authentication. 119type ClientAuthType int 120 121const ( 122 NoClientCert ClientAuthType = iota 123 RequestClientCert 124 RequireAnyClientCert 125 VerifyClientCertIfGiven 126 RequireAndVerifyClientCert 127) 128 129// A Config structure is used to configure a TLS client or server. After one 130// has been passed to a TLS function it must not be modified. 131type Config struct { 132 // Rand provides the source of entropy for nonces and RSA blinding. 133 // If Rand is nil, TLS uses the cryptographic random reader in package 134 // crypto/rand. 135 Rand io.Reader 136 137 // Time returns the current time as the number of seconds since the epoch. 138 // If Time is nil, TLS uses time.Now. 139 Time func() time.Time 140 141 // Certificates contains one or more certificate chains 142 // to present to the other side of the connection. 143 // Server configurations must include at least one certificate. 144 Certificates []Certificate 145 146 // NameToCertificate maps from a certificate name to an element of 147 // Certificates. Note that a certificate name can be of the form 148 // '*.example.com' and so doesn't have to be a domain name as such. 149 // See Config.BuildNameToCertificate 150 // The nil value causes the first element of Certificates to be used 151 // for all connections. 152 NameToCertificate map[string]*Certificate 153 154 // RootCAs defines the set of root certificate authorities 155 // that clients use when verifying server certificates. 156 // If RootCAs is nil, TLS uses the host's root CA set. 157 RootCAs *x509.CertPool 158 159 // NextProtos is a list of supported, application level protocols. 160 NextProtos []string 161 162 // ServerName is included in the client's handshake to support virtual 163 // hosting. 164 ServerName string 165 166 // ClientAuth determines the server's policy for 167 // TLS Client Authentication. The default is NoClientCert. 168 ClientAuth ClientAuthType 169 170 // ClientCAs defines the set of root certificate authorities 171 // that servers use if required to verify a client certificate 172 // by the policy in ClientAuth. 173 ClientCAs *x509.CertPool 174 175 // InsecureSkipVerify controls whether a client verifies the 176 // server's certificate chain and host name. 177 // If InsecureSkipVerify is true, TLS accepts any certificate 178 // presented by the server and any host name in that certificate. 179 // In this mode, TLS is susceptible to man-in-the-middle attacks. 180 // This should be used only for testing. 181 InsecureSkipVerify bool 182 183 // CipherSuites is a list of supported cipher suites. If CipherSuites 184 // is nil, TLS uses a list of suites supported by the implementation. 185 CipherSuites []uint16 186 187 // PreferServerCipherSuites controls whether the server selects the 188 // client's most preferred ciphersuite, or the server's most preferred 189 // ciphersuite. If true then the server's preference, as expressed in 190 // the order of elements in CipherSuites, is used. 191 PreferServerCipherSuites bool 192 193 // SessionTicketsDisabled may be set to true to disable session ticket 194 // (resumption) support. 195 SessionTicketsDisabled bool 196 197 // SessionTicketKey is used by TLS servers to provide session 198 // resumption. See RFC 5077. If zero, it will be filled with 199 // random data before the first server handshake. 200 // 201 // If multiple servers are terminating connections for the same host 202 // they should all have the same SessionTicketKey. If the 203 // SessionTicketKey leaks, previously recorded and future TLS 204 // connections using that key are compromised. 205 SessionTicketKey [32]byte 206 207 serverInitOnce sync.Once 208} 209 210func (c *Config) rand() io.Reader { 211 r := c.Rand 212 if r == nil { 213 return rand.Reader 214 } 215 return r 216} 217 218func (c *Config) time() time.Time { 219 t := c.Time 220 if t == nil { 221 t = time.Now 222 } 223 return t() 224} 225 226func (c *Config) cipherSuites() []uint16 { 227 s := c.CipherSuites 228 if s == nil { 229 s = defaultCipherSuites() 230 } 231 return s 232} 233 234// getCertificateForName returns the best certificate for the given name, 235// defaulting to the first element of c.Certificates if there are no good 236// options. 237func (c *Config) getCertificateForName(name string) *Certificate { 238 if len(c.Certificates) == 1 || c.NameToCertificate == nil { 239 // There's only one choice, so no point doing any work. 240 return &c.Certificates[0] 241 } 242 243 name = strings.ToLower(name) 244 for len(name) > 0 && name[len(name)-1] == '.' { 245 name = name[:len(name)-1] 246 } 247 248 if cert, ok := c.NameToCertificate[name]; ok { 249 return cert 250 } 251 252 // try replacing labels in the name with wildcards until we get a 253 // match. 254 labels := strings.Split(name, ".") 255 for i := range labels { 256 labels[i] = "*" 257 candidate := strings.Join(labels, ".") 258 if cert, ok := c.NameToCertificate[candidate]; ok { 259 return cert 260 } 261 } 262 263 // If nothing matches, return the first certificate. 264 return &c.Certificates[0] 265} 266 267// BuildNameToCertificate parses c.Certificates and builds c.NameToCertificate 268// from the CommonName and SubjectAlternateName fields of each of the leaf 269// certificates. 270func (c *Config) BuildNameToCertificate() { 271 c.NameToCertificate = make(map[string]*Certificate) 272 for i := range c.Certificates { 273 cert := &c.Certificates[i] 274 x509Cert, err := x509.ParseCertificate(cert.Certificate[0]) 275 if err != nil { 276 continue 277 } 278 if len(x509Cert.Subject.CommonName) > 0 { 279 c.NameToCertificate[x509Cert.Subject.CommonName] = cert 280 } 281 for _, san := range x509Cert.DNSNames { 282 c.NameToCertificate[san] = cert 283 } 284 } 285} 286 287// A Certificate is a chain of one or more certificates, leaf first. 288type Certificate struct { 289 Certificate [][]byte 290 PrivateKey crypto.PrivateKey // supported types: *rsa.PrivateKey 291 // OCSPStaple contains an optional OCSP response which will be served 292 // to clients that request it. 293 OCSPStaple []byte 294 // Leaf is the parsed form of the leaf certificate, which may be 295 // initialized using x509.ParseCertificate to reduce per-handshake 296 // processing for TLS clients doing client authentication. If nil, the 297 // leaf certificate will be parsed as needed. 298 Leaf *x509.Certificate 299} 300 301// A TLS record. 302type record struct { 303 contentType recordType 304 major, minor uint8 305 payload []byte 306} 307 308type handshakeMessage interface { 309 marshal() []byte 310 unmarshal([]byte) bool 311} 312 313// mutualVersion returns the protocol version to use given the advertised 314// version of the peer. 315func mutualVersion(vers uint16) (uint16, bool) { 316 if vers < minVersion { 317 return 0, false 318 } 319 if vers > maxVersion { 320 vers = maxVersion 321 } 322 return vers, true 323} 324 325var emptyConfig Config 326 327func defaultConfig() *Config { 328 return &emptyConfig 329} 330 331var ( 332 once sync.Once 333 varDefaultCipherSuites []uint16 334) 335 336func defaultCipherSuites() []uint16 { 337 once.Do(initDefaultCipherSuites) 338 return varDefaultCipherSuites 339} 340 341func initDefaultCipherSuites() { 342 varDefaultCipherSuites = make([]uint16, len(cipherSuites)) 343 for i, suite := range cipherSuites { 344 varDefaultCipherSuites[i] = suite.id 345 } 346} 347