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 // guards calling (*Config).serverInit 208} 209 210func (c *Config) serverInit() { 211 if c.SessionTicketsDisabled { 212 return 213 } 214 215 // If the key has already been set then we have nothing to do. 216 for _, b := range c.SessionTicketKey { 217 if b != 0 { 218 return 219 } 220 } 221 222 if _, err := io.ReadFull(c.rand(), c.SessionTicketKey[:]); err != nil { 223 c.SessionTicketsDisabled = true 224 } 225} 226 227func (c *Config) rand() io.Reader { 228 r := c.Rand 229 if r == nil { 230 return rand.Reader 231 } 232 return r 233} 234 235func (c *Config) time() time.Time { 236 t := c.Time 237 if t == nil { 238 t = time.Now 239 } 240 return t() 241} 242 243func (c *Config) cipherSuites() []uint16 { 244 s := c.CipherSuites 245 if s == nil { 246 s = defaultCipherSuites() 247 } 248 return s 249} 250 251// getCertificateForName returns the best certificate for the given name, 252// defaulting to the first element of c.Certificates if there are no good 253// options. 254func (c *Config) getCertificateForName(name string) *Certificate { 255 if len(c.Certificates) == 1 || c.NameToCertificate == nil { 256 // There's only one choice, so no point doing any work. 257 return &c.Certificates[0] 258 } 259 260 name = strings.ToLower(name) 261 for len(name) > 0 && name[len(name)-1] == '.' { 262 name = name[:len(name)-1] 263 } 264 265 if cert, ok := c.NameToCertificate[name]; ok { 266 return cert 267 } 268 269 // try replacing labels in the name with wildcards until we get a 270 // match. 271 labels := strings.Split(name, ".") 272 for i := range labels { 273 labels[i] = "*" 274 candidate := strings.Join(labels, ".") 275 if cert, ok := c.NameToCertificate[candidate]; ok { 276 return cert 277 } 278 } 279 280 // If nothing matches, return the first certificate. 281 return &c.Certificates[0] 282} 283 284// BuildNameToCertificate parses c.Certificates and builds c.NameToCertificate 285// from the CommonName and SubjectAlternateName fields of each of the leaf 286// certificates. 287func (c *Config) BuildNameToCertificate() { 288 c.NameToCertificate = make(map[string]*Certificate) 289 for i := range c.Certificates { 290 cert := &c.Certificates[i] 291 x509Cert, err := x509.ParseCertificate(cert.Certificate[0]) 292 if err != nil { 293 continue 294 } 295 if len(x509Cert.Subject.CommonName) > 0 { 296 c.NameToCertificate[x509Cert.Subject.CommonName] = cert 297 } 298 for _, san := range x509Cert.DNSNames { 299 c.NameToCertificate[san] = cert 300 } 301 } 302} 303 304// A Certificate is a chain of one or more certificates, leaf first. 305type Certificate struct { 306 Certificate [][]byte 307 PrivateKey crypto.PrivateKey // supported types: *rsa.PrivateKey 308 // OCSPStaple contains an optional OCSP response which will be served 309 // to clients that request it. 310 OCSPStaple []byte 311 // Leaf is the parsed form of the leaf certificate, which may be 312 // initialized using x509.ParseCertificate to reduce per-handshake 313 // processing for TLS clients doing client authentication. If nil, the 314 // leaf certificate will be parsed as needed. 315 Leaf *x509.Certificate 316} 317 318// A TLS record. 319type record struct { 320 contentType recordType 321 major, minor uint8 322 payload []byte 323} 324 325type handshakeMessage interface { 326 marshal() []byte 327 unmarshal([]byte) bool 328} 329 330// mutualVersion returns the protocol version to use given the advertised 331// version of the peer. 332func mutualVersion(vers uint16) (uint16, bool) { 333 if vers < minVersion { 334 return 0, false 335 } 336 if vers > maxVersion { 337 vers = maxVersion 338 } 339 return vers, true 340} 341 342var emptyConfig Config 343 344func defaultConfig() *Config { 345 return &emptyConfig 346} 347 348var ( 349 once sync.Once 350 varDefaultCipherSuites []uint16 351) 352 353func defaultCipherSuites() []uint16 { 354 once.Do(initDefaultCipherSuites) 355 return varDefaultCipherSuites 356} 357 358func initDefaultCipherSuites() { 359 varDefaultCipherSuites = make([]uint16, len(cipherSuites)) 360 for i, suite := range cipherSuites { 361 varDefaultCipherSuites[i] = suite.id 362 } 363} 364