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