# package tls `import "crypto/tls"` tls包實現了TLS 1.2，細節參見[RFC 5246](http://tools.ietf.org/html/rfc5246)。 ## Index * [Constants](#pkg-constants) * [type ClientAuthType](#ClientAuthType) * [type CurveID](#CurveID) * [type Certificate](#Certificate) * [func LoadX509KeyPair(certFile, keyFile string) (cert Certificate, err error)](#LoadX509KeyPair) * [func X509KeyPair(certPEMBlock, keyPEMBlock []byte) (cert Certificate, err error)](#X509KeyPair) * [type ClientSessionState](#ClientSessionState) * [type ClientSessionCache](#ClientSessionCache) * [func NewLRUClientSessionCache(capacity int) ClientSessionCache](#NewLRUClientSessionCache) * [type Config](#Config) * [func (c \*Config) BuildNameToCertificate()](#Config.BuildNameToCertificate) * [type ConnectionState](#ConnectionState) * [type Conn](#Conn) * [func (c \*Conn) LocalAddr() net.Addr](#Conn.LocalAddr) * [func (c \*Conn) RemoteAddr() net.Addr](#Conn.RemoteAddr) * [func (c \*Conn) ConnectionState() ConnectionState](#Conn.ConnectionState) * [func (c \*Conn) SetDeadline(t time.Time) error](#Conn.SetDeadline) * [func (c \*Conn) SetReadDeadline(t time.Time) error](#Conn.SetReadDeadline) * [func (c \*Conn) SetWriteDeadline(t time.Time) error](#Conn.SetWriteDeadline) * [func (c \*Conn) Handshake() error](#Conn.Handshake) * [func (c \*Conn) VerifyHostname(host string) error](#Conn.VerifyHostname) * [func (c \*Conn) OCSPResponse() []byte](#Conn.OCSPResponse) * [func (c \*Conn) Read(b []byte) (n int, err error)](#Conn.Read) * [func (c \*Conn) Write(b []byte) (int, error)](#Conn.Write) * [func (c \*Conn) Close() error](#Conn.Close) * [func Client(conn net.Conn, config \*Config) \*Conn](#Client) * [func Server(conn net.Conn, config \*Config) \*Conn](#Server) * [func Dial(network, addr string, config \*Config) (\*Conn, error)](#Dial) * [func DialWithDialer(dialer \*net.Dialer, network, addr string, config \*Config) (\*Conn, error)](#DialWithDialer) * [func Listen(network, laddr string, config \*Config) (net.Listener, error)](#Listen) * [func NewListener(inner net.Listener, config \*Config) net.Listener](#NewListener) ### Examples * [Dial](#example-Dial) ## Constants ``` const ( TLS_RSA_WITH_RC4_128_SHA uint16 = 0x0005 TLS_RSA_WITH_3DES_EDE_CBC_SHA uint16 = 0x000a TLS_RSA_WITH_AES_128_CBC_SHA uint16 = 0x002f TLS_RSA_WITH_AES_256_CBC_SHA uint16 = 0x0035 TLS_ECDHE_ECDSA_WITH_RC4_128_SHA uint16 = 0xc007 TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA uint16 = 0xc009 TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA uint16 = 0xc00a TLS_ECDHE_RSA_WITH_RC4_128_SHA uint16 = 0xc011 TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA uint16 = 0xc012 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA uint16 = 0xc013 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA uint16 = 0xc014 TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 uint16 = 0xc02f TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 uint16 = 0xc02b ) ``` 可選的加密組的ID的列表。參見：[http://www.iana.org/assignments/tls-parameters/tls-parameters.xml](http://www.iana.org/assignments/tls-parameters/tls-parameters.xml) ``` const ( VersionSSL30 = 0x0300 VersionTLS10 = 0x0301 VersionTLS11 = 0x0302 VersionTLS12 = 0x0303 ) ``` ## type [ClientAuthType](https://github.com/golang/go/blob/master/src/crypto/tls/common.go#L171 "View Source") ``` type ClientAuthType int ``` ClientAuthType類型聲明服務端將遵循的TLS客戶端驗證策略。 ``` const ( NoClientCert ClientAuthType = iota RequestClientCert RequireAnyClientCert VerifyClientCertIfGiven RequireAndVerifyClientCert ) ``` ## type [CurveID](https://github.com/golang/go/blob/master/src/crypto/tls/common.go#L87 "View Source") ``` type CurveID uint16 ``` CurveID是TLS橢圓曲線的標識符的類型。 參見：?[http://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-8](http://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-8) ``` const ( CurveP256 CurveID = 23 CurveP384 CurveID = 24 CurveP521 CurveID = 25 ) ``` ## type [Certificate](https://github.com/golang/go/blob/master/src/crypto/tls/common.go#L440 "View Source") ``` type Certificate struct { Certificate [][]byte PrivateKey crypto.PrivateKey // 只支持rsa.PrivateKey和*ecdsa.PrivateKey類型 // OCSPStaple包含一個可選的OCSP staple的回復，當客戶端要求時用于回復客戶端 OCSPStaple []byte // Leaf是解析后的葉證書，可以使用x509.ParseCertificate初始化， // 以簡化每次TLS客戶端進行客戶端認證時握手的過程。如果Leaf是nil，葉證書會根據需要解析。 Leaf *x509.Certificate } ``` Certificate是一個或多個證書的鏈條，葉證書在最前面。 ### func [LoadX509KeyPair](https://github.com/golang/go/blob/master/src/crypto/tls/tls.go#L170 "View Source") ``` func LoadX509KeyPair(certFile, keyFile string) (cert Certificate, err error) ``` LoadX509KeyPair讀取并解析一對文件獲取公鑰和私鑰。這些文件必須是PEM編碼的。 ### func [X509KeyPair](https://github.com/golang/go/blob/master/src/crypto/tls/tls.go#L184 "View Source") ``` func X509KeyPair(certPEMBlock, keyPEMBlock []byte) (cert Certificate, err error) ``` X509KeyPair解析一對PEM編碼的數據獲取公鑰和私鑰。 ## type [ClientSessionState](https://github.com/golang/go/blob/master/src/crypto/tls/common.go#L183 "View Source") ``` type ClientSessionState struct { // 內含隱藏或非導出字段 } ``` ClientSessionState包含客戶端所需的用于恢復TLS會話的狀態。 ## type [ClientSessionCache](https://github.com/golang/go/blob/master/src/crypto/tls/common.go#L195 "View Source") ``` type ClientSessionCache interface { // Get搜索與給出的鍵相關聯的*ClientSessionState并用ok說明是否找到 Get(sessionKey string) (session *ClientSessionState, ok bool) // Put將*ClientSessionState與給出的鍵關聯并寫入緩存中 Put(sessionKey string, cs *ClientSessionState) } ``` ClientSessionCache是ClientSessionState對象的緩存，可以被客戶端用于恢復與某個服務端的TLS會話。本類型的實現期望被不同線程并行的調用。 ### func [NewLRUClientSessionCache](https://github.com/golang/go/blob/master/src/crypto/tls/common.go#L483 "View Source") ``` func NewLRUClientSessionCache(capacity int) ClientSessionCache ``` 函數使用給出的容量創建一個采用LRU策略的ClientSessionState，如果capacity<1會采用默認容量。 ## type [Config](https://github.com/golang/go/blob/master/src/crypto/tls/common.go#L208 "View Source") ``` type Config struct { // Rand提供用于生成隨機數和RSA盲簽名的熵源，該接口必須能安全的用于并發。 // 如果Rand是nil，會使用crypto/rand包的密碼用隨機數讀取器。 Rand io.Reader // Time返回當前時間，如果是nil會使用time.Now。 Time func() time.Time // 不少于一個證書的鏈，用于提供給連接的另一端，服務端必須保證至少有一個證書。 Certificates []Certificate // NameToCertificate映射證書名到證書。 // 注意證書名可以是"*.example.com "的格式，因此證書名不是必須為域名。 // 參見Config.BuildNameToCertificate方法。 // 如本字段為nil，Certificates字段的第一個成員會被用于所有連接。 NameToCertificate map[string]*Certificate // RootCAs定義權威根證書，客戶端會在驗證服務端證書時用到本字段。 // 如果RootCAs是nil，TLS會使用主機的根CA池。 RootCAs *x509.CertPool // 可以支持的應用層協議的列表 NextProtos []string // 用于認證返回證書的主機名（除非設置了InsecureSkipVerify）。 // 也被用在客戶端的握手里，以支持虛擬主機。 ServerName string // ClientAuth決定服務端的認證策略，默認是NoClientCert。 ClientAuth ClientAuthType // ClientCAs定義權威根證書，服務端會在采用ClientAuth策略時使用它來認證客戶端證書。 ClientCAs *x509.CertPool // InsecureSkipVerify控制客戶端是否認證服務端的證書鏈和主機名。 // 如果InsecureSkipVerify為真，TLS連接會接受服務端提供的任何證書和該證書中的任何主機名。 // 此時，TLS連接容易遭受中間人攻擊，這種設置只應用于測試。 InsecureSkipVerify bool // CipherSuites是支持的加密組合列表。如果CipherSuites為nil， // TLS連接會使用本包的實現支持的密碼組合列表。 CipherSuites []uint16 // 本字段控制服務端是選擇客戶端最期望的密碼組合還是服務端最期望的密碼組合。 // 如果本字段為真，服務端會優先選擇CipherSuites字段中靠前的密碼組合使用。 PreferServerCipherSuites bool // SessionTicketsDisabled可以設為假以關閉會話恢復支持。 SessionTicketsDisabled bool // SessionTicketKey被TLS服務端用于提供哦你會話恢復服務，參見RFC 5077。 // 如果本字段為零值，它會在第一次服務端握手之前填寫上隨機數據。 // // 如果多個服務端都在終止和同一主機的連接，它們應擁有相同的SessionTicketKey。 // 如果SessionTicketKey泄露了，使用該鍵的之前的記錄和未來的TLS連接可能會被盜用。 SessionTicketKey [32]byte // SessionCache是ClientSessionState的緩存，用于恢復TLS會話。 ClientSessionCache ClientSessionCache // MinVersion包含可接受的最低SSL/TLS版本。如果為0，會將SSLv3作為最低版本。 MinVersion uint16 // MaxVersion包含可接受的最高SSL/TLS版本。 // 如果為0，會將本包使用的版本作為最高版本，目前是TLS 1.2。 MaxVersion uint16 // 本字段包含用于ECDHE握手的橢圓曲線的ID，按優先度排序。如為空，會使用默認值。 CurvePreferences []CurveID // 內含隱藏或非導出字段 } ``` Config結構類型用于配置TLS客戶端或服務端。在本類型的值提供給TLS函數后，就不應再修改該值。Config類型值可能被重用；tls包也不會修改它。 ### func (\*Config) [BuildNameToCertificate](https://github.com/golang/go/blob/master/src/crypto/tls/common.go#L422 "View Source") ``` func (c *Config) BuildNameToCertificate() ``` BuildNameToCertificate解析c.Certificates并將每一個葉證書的CommonName和SubjectAlternateName字段用于創建c.NameToCertificate。 ## type [ConnectionState](https://github.com/golang/go/blob/master/src/crypto/tls/common.go#L157 "View Source") ``` type ConnectionState struct { Version uint16 // 連接使用的TLS版本 HandshakeComplete bool // TLS握手是否完成 DidResume bool // 連接恢復了之前的TLS連接 CipherSuite uint16 // 使用的加密程序組合 NegotiatedProtocol string // 商定的下一層協議 NegotiatedProtocolIsMutual bool // 商定的協議是服務端建議的 ServerName string // 服務端名（僅服務端有） PeerCertificates []*x509.Certificate // 遠端提供的證書鏈 VerifiedChains [][]*x509.Certificate // 從PeerCertificates建立的認證鏈 } ``` ConnectionState類型記錄連接的基本TLS細節。 ## type [Conn](https://github.com/golang/go/blob/master/src/crypto/tls/conn.go#L24 "View Source") ``` type Conn struct { // 內含隱藏或非導出字段 } ``` Conn代表一個安全連接。本類型實現了net.Conn接口。 ### func (\*Conn) [LocalAddr](https://github.com/golang/go/blob/master/src/crypto/tls/conn.go#L63 "View Source") ``` func (c *Conn) LocalAddr() net.Addr ``` LocalAddr返回本地網絡地址。 ### func (\*Conn) [RemoteAddr](https://github.com/golang/go/blob/master/src/crypto/tls/conn.go#L68 "View Source") ``` func (c *Conn) RemoteAddr() net.Addr ``` LocalAddr返回遠端網絡地址。 ### func (\*Conn) [ConnectionState](https://github.com/golang/go/blob/master/src/crypto/tls/conn.go#L982 "View Source") ``` func (c *Conn) ConnectionState() ConnectionState ``` ConnectionState返回該連接的基本TLS細節。 ### func (\*Conn) [SetDeadline](https://github.com/golang/go/blob/master/src/crypto/tls/conn.go#L75 "View Source") ``` func (c *Conn) SetDeadline(t time.Time) error ``` SetDeadline設置該連接的讀寫操作絕對期限。t為Time零值表示不設置超時。在一次Write/Read方法超時后，TLS連接狀態會被破壞，之后所有的讀寫操作都會返回同一錯誤。 ### func (\*Conn) [SetReadDeadline](https://github.com/golang/go/blob/master/src/crypto/tls/conn.go#L81 "View Source") ``` func (c *Conn) SetReadDeadline(t time.Time) error ``` SetReadDeadline設置該連接的讀操作絕對期限。t為Time零值表示不設置超時。 ### func (\*Conn) [SetWriteDeadline](https://github.com/golang/go/blob/master/src/crypto/tls/conn.go#L88 "View Source") ``` func (c *Conn) SetWriteDeadline(t time.Time) error ``` SetReadDeadline設置該連接的寫操作絕對期限。t為Time零值表示不設置超時。在一次Write方法超時后，TLS連接狀態會被破壞，之后所有的寫操作都會返回同一錯誤。 ### func (\*Conn) [Handshake](https://github.com/golang/go/blob/master/src/crypto/tls/conn.go#L963 "View Source") ``` func (c *Conn) Handshake() error ``` Handshake執行客戶端或服務端的握手協議（如果還沒有執行的話）。本包的大多數應用不需要顯式的調用Handsake方法：第一次Read或Write方法會自動調用本方法。 ### func (\*Conn) [VerifyHostname](https://github.com/golang/go/blob/master/src/crypto/tls/conn.go#L1014 "View Source") ``` func (c *Conn) VerifyHostname(host string) error ``` VerifyHostname檢查用于連接到host的對等實體證書鏈是否合法。如果合法，它會返回nil；否則，會返回一個描述該問題的錯誤。 ### func (\*Conn) [OCSPResponse](https://github.com/golang/go/blob/master/src/crypto/tls/conn.go#L1004 "View Source") ``` func (c *Conn) OCSPResponse() []byte ``` OCSPResponse返回來自服務端的OCSP staple回復（如果有）。只有客戶端可以使用本方法。 ### func (\*Conn) [Read](https://github.com/golang/go/blob/master/src/crypto/tls/conn.go#L883 "View Source") ``` func (c *Conn) Read(b []byte) (n int, err error) ``` Read從連接讀取數據，可設置超時，參見SetDeadline和SetReadDeadline。 ### func (\*Conn) [Write](https://github.com/golang/go/blob/master/src/crypto/tls/conn.go#L841 "View Source") ``` func (c *Conn) Write(b []byte) (int, error) ``` Write將數據寫入連接，可設置超時，參見SetDeadline和SetWriteDeadline。 ### func (\*Conn) [Close](https://github.com/golang/go/blob/master/src/crypto/tls/conn.go#L944 "View Source") ``` func (c *Conn) Close() error ``` Close關閉連接。 ## func [Client](https://github.com/golang/go/blob/master/src/crypto/tls/tls.go#L33 "View Source") ``` func Client(conn net.Conn, config *Config) *Conn ``` Client使用conn作為下層傳輸接口返回一個TLS連接的客戶端側。配置參數config必須是非nil的且必須設置了ServerName或者InsecureSkipVerify字段。 ## func [Server](https://github.com/golang/go/blob/master/src/crypto/tls/tls.go#L25 "View Source") ``` func Server(conn net.Conn, config *Config) *Conn ``` Server使用conn作為下層傳輸接口返回一個TLS連接的服務端側。配置參數config必須是非nil的且必須含有至少一個證書。 ## func [Dial](https://github.com/golang/go/blob/master/src/crypto/tls/tls.go#L164 "View Source") ``` func Dial(network, addr string, config *Config) (*Conn, error) ``` Dial使用net.Dial連接指定的網絡和地址，然后發起TLS握手，返回生成的TLS連接。Dial會將nil的配置視為零值的配置；參見Config類型的文檔獲取細節。 Example ``` // Connecting with a custom root-certificate set. const rootPEM = ` -----BEGIN CERTIFICATE----- MIIEBDCCAuygAwIBAgIDAjppMA0GCSqGSIb3DQEBBQUAMEIxCzAJBgNVBAYTAlVT MRYwFAYDVQQKEw1HZW9UcnVzdCBJbmMuMRswGQYDVQQDExJHZW9UcnVzdCBHbG9i YWwgQ0EwHhcNMTMwNDA1MTUxNTU1WhcNMTUwNDA0MTUxNTU1WjBJMQswCQYDVQQG EwJVUzETMBEGA1UEChMKR29vZ2xlIEluYzElMCMGA1UEAxMcR29vZ2xlIEludGVy bmV0IEF1dGhvcml0eSBHMjCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEB AJwqBHdc2FCROgajguDYUEi8iT/xGXAaiEZ+4I/F8YnOIe5a/mENtzJEiaB0C1NP VaTOgmKV7utZX8bhBYASxF6UP7xbSDj0U/ck5vuR6RXEz/RTDfRK/J9U3n2+oGtv h8DQUB8oMANA2ghzUWx//zo8pzcGjr1LEQTrfSTe5vn8MXH7lNVg8y5Kr0LSy+rE ahqyzFPdFUuLH8gZYR/Nnag+YyuENWllhMgZxUYi+FOVvuOAShDGKuy6lyARxzmZ EASg8GF6lSWMTlJ14rbtCMoU/M4iarNOz0YDl5cDfsCx3nuvRTPPuj5xt970JSXC DTWJnZ37DhF5iR43xa+OcmkCAwEAAaOB+zCB+DAfBgNVHSMEGDAWgBTAephojYn7 qwVkDBF9qn1luMrMTjAdBgNVHQ4EFgQUSt0GFhu89mi1dvWBtrtiGrpagS8wEgYD VR0TAQH/BAgwBgEB/wIBADAOBgNVHQ8BAf8EBAMCAQYwOgYDVR0fBDMwMTAvoC2g K4YpaHR0cDovL2NybC5nZW90cnVzdC5jb20vY3Jscy9ndGdsb2JhbC5jcmwwPQYI KwYBBQUHAQEEMTAvMC0GCCsGAQUFBzABhiFodHRwOi8vZ3RnbG9iYWwtb2NzcC5n ZW90cnVzdC5jb20wFwYDVR0gBBAwDjAMBgorBgEEAdZ5AgUBMA0GCSqGSIb3DQEB BQUAA4IBAQA21waAESetKhSbOHezI6B1WLuxfoNCunLaHtiONgaX4PCVOzf9G0JY /iLIa704XtE7JW4S615ndkZAkNoUyHgN7ZVm2o6Gb4ChulYylYbc3GrKBIxbf/a/ zG+FA1jDaFETzf3I93k9mTXwVqO94FntT0QJo544evZG0R0SnU++0ED8Vf4GXjza HFa9llF7b1cq26KqltyMdMKVvvBulRP/F/A8rLIQjcxz++iPAsbw+zOzlTvjwsto WHPbqCRiOwY1nQ2pM714A5AuTHhdUDqB1O6gyHA43LL5Z/qHQF1hwFGPa4NrzQU6 yuGnBXj8ytqU0CwIPX4WecigUCAkVDNx -----END CERTIFICATE-----` // First, create the set of root certificates. For this example we only // have one. It's also possible to omit this in order to use the // default root set of the current operating system. roots := x509.NewCertPool() ok := roots.AppendCertsFromPEM([]byte(rootPEM)) if !ok { panic("failed to parse root certificate") } conn, err := tls.Dial("tcp", "mail.google.com:443", &tls.Config{ RootCAs: roots, }) if err != nil { panic("failed to connect: " + err.Error()) } conn.Close() ``` ## func [DialWithDialer](https://github.com/golang/go/blob/master/src/crypto/tls/tls.go#L93 "View Source") ``` func DialWithDialer(dialer *net.Dialer, network, addr string, config *Config) (*Conn, error) ``` DialWithDialer使用dialer.Dial連接指定的網絡和地址，然后發起TLS握手，返回生成的TLS連接。dialer中的超時和期限設置會將連接和TLS握手作為一個整體來應用。 DialWithDialer會將nil的配置視為零值的配置；參見Config類型的文檔獲取細節。 ## func [Listen](https://github.com/golang/go/blob/master/src/crypto/tls/tls.go#L69 "View Source") ``` func Listen(network, laddr string, config *Config) (net.Listener, error) ``` 函數創建一個TLS監聽器，使用net.Listen函數接收給定地址上的連接。配置參數config必須是非nil的且必須含有至少一個證書。 ## func [NewListener](https://github.com/golang/go/blob/master/src/crypto/tls/tls.go#L58 "View Source") ``` func NewListener(inner net.Listener, config *Config) net.Listener ``` 函數創建一個TLS監聽器，該監聽器接受inner接收到的每一個連接，并調用Server函數包裝這些連接。配置參數config必須是非nil的且必須含有至少一個證書。