...

パッケージ tls

import "crypto/tls"
概要
目次

概要 ▾

tls パッケージは,RFC 5246 で定義された TLS 1.2 と RFC 8446 で定義された TLS 1.3 を部分的に実装します。

TLS 1.3 is available on an opt-out basis in Go 1.13. To disable it, set the GODEBUG environment variable (comma-separated key=value options) such that it includes "tls13=0".

目次 ▾

定数
func Listen(network, laddr string, config *Config) (net.Listener, error)
func NewListener(inner net.Listener, config *Config) net.Listener
type Certificate
    func LoadX509KeyPair(certFile, keyFile string) (Certificate, error)
    func X509KeyPair(certPEMBlock, keyPEMBlock []byte) (Certificate, error)
type CertificateRequestInfo
type ClientAuthType
type ClientHelloInfo
type ClientSessionCache
    func NewLRUClientSessionCache(capacity int) ClientSessionCache
type ClientSessionState
type Config
    func (c *Config) BuildNameToCertificate()
    func (c *Config) Clone() *Config
    func (c *Config) SetSessionTicketKeys(keys [][32]byte)
type Conn
    func Client(conn net.Conn, config *Config) *Conn
    func Dial(network, addr string, config *Config) (*Conn, error)
    func DialWithDialer(dialer *net.Dialer, network, addr string, config *Config) (*Conn, error)
    func Server(conn net.Conn, config *Config) *Conn
    func (c *Conn) Close() error
    func (c *Conn) CloseWrite() error
    func (c *Conn) ConnectionState() ConnectionState
    func (c *Conn) Handshake() error
    func (c *Conn) LocalAddr() net.Addr
    func (c *Conn) OCSPResponse() []byte
    func (c *Conn) Read(b []byte) (int, error)
    func (c *Conn) RemoteAddr() net.Addr
    func (c *Conn) SetDeadline(t time.Time) error
    func (c *Conn) SetReadDeadline(t time.Time) error
    func (c *Conn) SetWriteDeadline(t time.Time) error
    func (c *Conn) VerifyHostname(host string) error
    func (c *Conn) Write(b []byte) (int, error)
type ConnectionState
    func (cs *ConnectionState) ExportKeyingMaterial(label string, context []byte, length int) ([]byte, error)
type CurveID
type RecordHeaderError
    func (e RecordHeaderError) Error() string
type RenegotiationSupport
type SignatureScheme

パッケージファイル

alert.go auth.go cipher_suites.go common.go conn.go handshake_client.go handshake_client_tls13.go handshake_messages.go handshake_server.go handshake_server_tls13.go key_agreement.go key_schedule.go prf.go ticket.go tls.go

定数

このパッケージによって実装されている暗号スイート ID のリスト。

https://www.iana.org/assignments/tls-parameters/tls-parameters.xml から取得しました

const (
    // TLS 1.0 - 1.2 暗号スイート。
    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_RSA_WITH_AES_128_CBC_SHA256         uint16 = 0x003c
    TLS_RSA_WITH_AES_128_GCM_SHA256         uint16 = 0x009c
    TLS_RSA_WITH_AES_256_GCM_SHA384         uint16 = 0x009d
    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_ECDSA_WITH_AES_128_CBC_SHA256 uint16 = 0xc023
    TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256   uint16 = 0xc027
    TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256   uint16 = 0xc02f
    TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 uint16 = 0xc02b
    TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384   uint16 = 0xc030
    TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 uint16 = 0xc02c
    TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305    uint16 = 0xcca8
    TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305  uint16 = 0xcca9

    // TLS 1.3 暗号スイート。
    TLS_AES_128_GCM_SHA256       uint16 = 0x1301
    TLS_AES_256_GCM_SHA384       uint16 = 0x1302
    TLS_CHACHA20_POLY1305_SHA256 uint16 = 0x1303

    // TLS_FALLBACK_SCSV は標準の暗号スイートではありませんが,クライアントがバージョンフォールバックを行っていることを示す指標です。
    // RFC 7507 を参照してください。
    TLS_FALLBACK_SCSV uint16 = 0x5600
)
const (
    VersionTLS10 = 0x0301
    VersionTLS11 = 0x0302
    VersionTLS12 = 0x0303
    VersionTLS13 = 0x0304

    // Deprecated: SSLv3 is cryptographically broken, and will be
    // removed in Go 1.14. See golang.org/issue/32716.
    VersionSSL30 = 0x0300
)

func Listen

func Listen(network, laddr string, config *Config) (net.Listener, error)

Listen は, net.Listen を使用して,指定されたネットワークアドレス上の接続を受け入れる TLS リスナーを作成します。 Config設定は nil 以外でなければならず,少なくとも 1 つの証明書を含むか,そうでなければ GetCertificate を設定する必要があります。

func NewListener

func NewListener(inner net.Listener, config *Config) net.Listener

NewListener は,内部の Listener からの接続を受け付け, Server との各接続をラップする Listener を作成します。 Config設定は nil 以外でなければならず,少なくとも 1 つの証明書を含むか,そうでなければ GetCertificate を設定する必要があります。

type Certificate

Certificate (証明書) は 1 つ以上の証明書のチェーンで,リーフが最初となります。

type Certificate struct {
    Certificate [][]byte
    // PrivateKey contains the private key corresponding to the public key in
    // Leaf. This must implement crypto.Signer with an RSA, ECDSA or Ed25519 PublicKey.
    // For a server up to TLS 1.2, it can also implement crypto.Decrypter with
    // an RSA PublicKey.
    PrivateKey crypto.PrivateKey
    // OCSPStaple には,それをリクエストしたクライアントに渡されるオプションの OCSP レスポンスが含まれています。
    OCSPStaple []byte
    // SignedCertificateTimestamps は,それをリクエストするクライアントに渡される署名付き証明書タイムスタンプのオプションのリストを含みます。
    SignedCertificateTimestamps [][]byte // Go 1.5
    // Leaf は解析された形式のリーフ証明書です。
    // クライアント認証を行う TLS クライアントのハンドシェイクごとの処理を減らすために x509.ParseCertificate を使用して初期化できます。
    // nil の場合,リーフ証明書は必要に応じて解析されます。
    Leaf *x509.Certificate
}

func LoadX509KeyPair

func LoadX509KeyPair(certFile, keyFile string) (Certificate, error)

LoadX509KeyPair は,ファイルのペアから公開鍵と秘密鍵のペアを読み取り,解析します。 ファイルには PEM エンコードデータが含まれている必要があります。 証明書ファイルには,証明書チェーンを形成するためのリーフ証明書に続く中間証明書が含まれている場合があります。 正常に戻った場合,解析済み形式の証明書は保持されないため, Certificate.Leaf はゼロになります。

コード:

cert, err := tls.LoadX509KeyPair("testdata/example-cert.pem", "testdata/example-key.pem")
if err != nil {
    log.Fatal(err)
}
cfg := &tls.Config{Certificates: []tls.Certificate{cert}}
listener, err := tls.Listen("tcp", ":2000", cfg)
if err != nil {
    log.Fatal(err)
}
_ = listener

func X509KeyPair

func X509KeyPair(certPEMBlock, keyPEMBlock []byte) (Certificate, error)

X509KeyPair は, PEM でエンコードされたデータのペアから公開鍵と秘密鍵のペアを解析します。 正常に戻った場合,解析済み形式の証明書は保持されないため, Certificate.Leaf はゼロになります。

コード:

certPem := []byte(`-----BEGIN CERTIFICATE-----
MIIBhTCCASugAwIBAgIQIRi6zePL6mKjOipn+dNuaTAKBggqhkjOPQQDAjASMRAw
DgYDVQQKEwdBY21lIENvMB4XDTE3MTAyMDE5NDMwNloXDTE4MTAyMDE5NDMwNlow
EjEQMA4GA1UEChMHQWNtZSBDbzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABD0d
7VNhbWvZLWPuj/RtHFjvtJBEwOkhbN/BnnE8rnZR8+sbwnc/KhCk3FhnpHZnQz7B
5aETbbIgmuvewdjvSBSjYzBhMA4GA1UdDwEB/wQEAwICpDATBgNVHSUEDDAKBggr
BgEFBQcDATAPBgNVHRMBAf8EBTADAQH/MCkGA1UdEQQiMCCCDmxvY2FsaG9zdDo1
NDUzgg4xMjcuMC4wLjE6NTQ1MzAKBggqhkjOPQQDAgNIADBFAiEA2zpJEPQyz6/l
Wf86aX6PepsntZv2GYlA5UpabfT2EZICICpJ5h/iI+i341gBmLiAFQOyTDT+/wQc
6MF9+Yw1Yy0t
-----END CERTIFICATE-----`)
keyPem := []byte(`-----BEGIN EC PRIVATE KEY-----
MHcCAQEEIIrYSSNQFaA2Hwf1duRSxKtLYX5CB04fSeQ6tF1aY/PuoAoGCCqGSM49
AwEHoUQDQgAEPR3tU2Fta9ktY+6P9G0cWO+0kETA6SFs38GecTyudlHz6xvCdz8q
EKTcWGekdmdDPsHloRNtsiCa697B2O9IFA==
-----END EC PRIVATE KEY-----`)
cert, err := tls.X509KeyPair(certPem, keyPem)
if err != nil {
    log.Fatal(err)
}
cfg := &tls.Config{Certificates: []tls.Certificate{cert}}
listener, err := tls.Listen("tcp", ":2000", cfg)
if err != nil {
    log.Fatal(err)
}
_ = listener

例 (HttpServer)

コード:

certPem := []byte(`-----BEGIN CERTIFICATE-----
MIIBhTCCASugAwIBAgIQIRi6zePL6mKjOipn+dNuaTAKBggqhkjOPQQDAjASMRAw
DgYDVQQKEwdBY21lIENvMB4XDTE3MTAyMDE5NDMwNloXDTE4MTAyMDE5NDMwNlow
EjEQMA4GA1UEChMHQWNtZSBDbzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABD0d
7VNhbWvZLWPuj/RtHFjvtJBEwOkhbN/BnnE8rnZR8+sbwnc/KhCk3FhnpHZnQz7B
5aETbbIgmuvewdjvSBSjYzBhMA4GA1UdDwEB/wQEAwICpDATBgNVHSUEDDAKBggr
BgEFBQcDATAPBgNVHRMBAf8EBTADAQH/MCkGA1UdEQQiMCCCDmxvY2FsaG9zdDo1
NDUzgg4xMjcuMC4wLjE6NTQ1MzAKBggqhkjOPQQDAgNIADBFAiEA2zpJEPQyz6/l
Wf86aX6PepsntZv2GYlA5UpabfT2EZICICpJ5h/iI+i341gBmLiAFQOyTDT+/wQc
6MF9+Yw1Yy0t
-----END CERTIFICATE-----`)
keyPem := []byte(`-----BEGIN EC PRIVATE KEY-----
MHcCAQEEIIrYSSNQFaA2Hwf1duRSxKtLYX5CB04fSeQ6tF1aY/PuoAoGCCqGSM49
AwEHoUQDQgAEPR3tU2Fta9ktY+6P9G0cWO+0kETA6SFs38GecTyudlHz6xvCdz8q
EKTcWGekdmdDPsHloRNtsiCa697B2O9IFA==
-----END EC PRIVATE KEY-----`)
cert, err := tls.X509KeyPair(certPem, keyPem)
if err != nil {
    log.Fatal(err)
}
cfg := &tls.Config{Certificates: []tls.Certificate{cert}}
srv := &http.Server{
    TLSConfig:    cfg,
    ReadTimeout:  time.Minute,
    WriteTimeout: time.Minute,
}
log.Fatal(srv.ListenAndServeTLS("", ""))

type CertificateRequestInfo 1.8

CertificateRequestInfo には,サーバーの CertificateRequest メッセージからの情報が含まれています。 メッセージはクライアントに証明書と制御の証明をリクエストするために使用されます。

type CertificateRequestInfo struct {
    // AcceptableCA には,ゼロ以上の DER エンコードされた X.501 識別名が含まれています。
    // これらは,サーバーが返された証明書に署名を希望するルートまたは中間 CA の名前です。
    // 空のスライスは,サーバーに優先順位がないことを示します。
    AcceptableCAs [][]byte

    // SignatureSchemes は,サーバーが検証したいと思う署名方式をリストします。
    SignatureSchemes []SignatureScheme
}

type ClientAuthType

ClientAuthType は, TLS クライアント認証に関してサーバーが従うポリシーを宣言します。

type ClientAuthType int
const (
    NoClientCert ClientAuthType = iota
    RequestClientCert
    RequireAnyClientCert
    VerifyClientCertIfGiven
    RequireAndVerifyClientCert
)

type ClientHelloInfo 1.4

ClientHelloInfo は, GetCertificate コールバックで証明書を選択をガイドするための ClientHello メッセージの情報を含みます。

type ClientHelloInfo struct {
    // CipherSuites は,クライアントによってサポートされている CipherSuite をリストします (例 :TLS_AES_128_GCM_SHA256 , TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256) 。
    CipherSuites []uint16

    // ServerName は,仮想ホスティングをサポートするためにクライアントによってリクエストされたサーバーの名前を示します。
    // ServerName は,クライアントが SNI を使用している場合にのみ設定されます (RFC4366 ,セクション 3.1 を参照) 。
    ServerName string

    // SupportedCurves は,クライアントによってサポートされている楕円曲線をリストします。
    // SupportedCurves は, サポートされている楕円曲線拡張が使用されている場合にのみ設定されます (RFC4492 のセクション 5.1.1 を参照) 。
    SupportedCurves []CurveID

    // SupportedPoints は,クライアントによってサポートされているポイントフォーマットをリストします。
    // SupportedPoints は, サポートされているポイントフォーマットが使用されている場合にのみ設定されます (RFC4492 ,セクション 5.1.2 を参照) 。
    SupportedPoints []uint8

    // SignatureSchemes はクライアントが検証しても構わないと思っている署名とハッシュスキームをリストします。
    // SignatureSchemes は, 署名アルゴリズム拡張 が使用されている場合にのみ設定されます (RFC5246 ,セクション 7.4.1.4.1 を参照) 。
    SignatureSchemes []SignatureScheme // Go 1.8

    // SupportedProtos は,クライアントによってサポートされているアプリケーションプロトコルをリストします。
    // SupportedProtos は, アプリケーションレイヤプロトコルネゴシエーション拡張 が使用されている場合にのみ設定されます (RFC7301 のセクション 3.1 を参照) 。
    //
    // サーバーは, GetConfigForClient の戻り値に Config.NextProtos を設定することでプロトコルを選択できます。
    SupportedProtos []string // Go 1.8

    // SupportedVersions は,クライアントによってサポートされている TLS バージョンをリストします。
    // TLS バージョンが 1.3 未満の場合,これはクライアントによって公示された最大バージョンから推定されるため,最大値以外の値が使用された場合は拒否される可能性があります。
    SupportedVersions []uint16 // Go 1.8

    // Conn は接続の内部の net.Conn です。
    // この接続から読み書きしないでください。
    // それが原因で TLS 接続が失敗します。
    Conn net.Conn // Go 1.8
}

type ClientSessionCache 1.3

ClientSessionCache は,特定のサーバーとの TLS セッションを再開するためにクライアントが使用できる ClientSessionState オブジェクトのキャッシュです。 ClientSessionCache の実装は,異なるゴルーチンから平行に呼び出されることを期待するべきです。 TLS 1.2 までは, SessionID ベースの再開ではなく,チケットベースの再開のみが​​サポートされていました。 TLS 1.3 では,これらは PSK モードに統合されました。 これは,このインターフェースを介してサポートされています。

type ClientSessionCache interface {
    // Getは指定されたキーに関連付けられている ClientSessionState を検索します。
    // 戻ったとき,見つかった場合 ok が true です。
    Get(sessionKey string) (session *ClientSessionState, ok bool)

    // Put は与えられたキーで ClientSessionState をキャッシュに追加します。
    // TLS 1.3 サーバーが複数のセッションチケットを提供する場合,接続内で複数回呼び出されることがあります。
    // *ClientSessionState がnilで呼び出された場合は,キャッシュエントリを削除する必要があります。
    Put(sessionKey string, cs *ClientSessionState)
}

func NewLRUClientSessionCache 1.3

func NewLRUClientSessionCache(capacity int) ClientSessionCache

NewLRUClientSessionCache は, LRU 方式を使用して,指定された容量の ClientSessionCache を返します。 容量が 1 未満の場合は,代わりにデフォルトの容量が使用されます。

type ClientSessionState 1.3

ClientSessionState には, TLS セッションを再開するためにクライアントが必要とする状態が含まれています。

type ClientSessionState struct {
    // エクスポートされていないフィールドがあります
}

type Config

Config 構造体は, TLS クライアントまたはサーバーを構成するために使用されます。 TLS 関数に渡された後は,変更してはいけません。 Config は再利用されえます。 tls パッケージもそれを変更しません。

type Config struct {
    // Rand は nonce と RSA ブラインドのエントロピーの元を提供します。
    // Rand が nil の場合, TLS はcrypto/randパッケージ  の暗号化ランダムリーダーを使用します。
    // Reader は複数のゴルーチンによる使用に対して安全でなければなりません。
    Rand io.Reader

    // Time は,現在時刻をエポック以降の秒数として返します。
    // Time がゼロの場合, TLS は time.Now を使用します。
    Time func() time.Time

    // Certificatesには,接続の反対側に提示するための 1 つ以上の証明書チェーンが含まれています。
    // サーバー構成には,少なくとも 1 つの証明書を含めるか, GetCertificate を設定する必要があります。
    // クライアント認証を行うクライアントは,証明書または GetClientCertificate を設定するかもしれません。
    Certificates []Certificate

    // NameToCertificate は,証明書名から Certificates の要素にマップします。
    // 証明書名は "*.example.com" の形式にすることができるので,ドメイン名である必要はありません。
    // Config.BuildNameToCertificate を参照してください。
    // nil 値を指定すると,証明書の最初の要素がすべての接続に使用されます。
    NameToCertificate map[string]*Certificate

    // GetCertificate は,与えられた ClientHelloInfo に基づいて証明書を返します。
    // クライアントが SNI 情報を提供する場合,または証明書が空の場合にのみ呼び出されます。
    //
    // GetCertificate が nil であるか,または nil を返す場合,証明書は NameToCertificate から取得されます。
    // NameToCertificate が nil の場合, Certificates の最初の要素が使用されます。
    GetCertificate func(*ClientHelloInfo) (*Certificate, error) // Go 1.4

    // GetClientCertificate が nil でなければ,サーバーがクライアントから証明書をリクエストしたときに呼び出されます。
    // 設定した場合,Certificatesの内容は無視されます。
    //
    // GetClientCertificate がエラーを返した場合,ハンドシェイクは中止され,そのエラーが返されます。
    // それ以外の場合, GetClientCertificate は nil 以外の証明書を返す必要があります。
    // Certificate.Certificate が空の場合,証明書はサーバーに送信されません。
    // これがサーバーに受け入れられない場合は,ハンドシェイクを中止する可能性があります。
    //
    // 再ネゴシエーションが発生した場合,または TLS 1.3 が使用されている場合は,同じ接続に対して GetClientCertificate が複数回呼び出されることがあります。
    GetClientCertificate func(*CertificateRequestInfo) (*Certificate, error) // Go 1.8

    // GetConfigForClient が nil でなければ, ClientHello がクライアントから受信された後に呼び出されます。
    // この接続を処理するために使用される Config を変更するために, nil 以外の Config を返すことがあります。
    // 返されたConfigが nil の場合,元のConfigが使用されます。
    // このコールバックによって返された Config は,後で変更することはできません。
    //
    // GetConfigForClient が nil の場合, Server() に渡された Config がすべての接続に使用されます。
    //
    // 設定されていない場合,返された Config 内のフィールドに対して一意に,セッションチケットキーが元の Config から複製されます。
    // 具体的には, SetSessionTicketKeys が元の設定で呼び出され,返された設定では呼び出されなかった場合,元の設定からのチケットキーは使用前に新しい設定にコピーされます。
    // それ以外の場合, SessionTicketKey が元の設定で設定されていて返された設定で設定されていない場合は,使用前に返された設定にコピーされます。
    // どちらの場合も当てはまらない場合は,返された設定からのキーマテリアルがセッションチケットに使用されます。
    GetConfigForClient func(*ClientHelloInfo) (*Config, error) // Go 1.8

    // VerifyPeerCertificate が nil でなければ, TLS クライアントまたはサーバーによる通常の証明書検証の後に呼び出されます。
    // それはピアによって渡された生の ASN.1 証明書と通常の処理が見つけたすべての検証済みチェーンも受け取ります。
    // nil 以外のエラーが返された場合,ハンドシェイクは中止され,そのエラーが発生します。
    //
    // 通常の検証が失敗すると,このコールバックを考慮する前にハンドシェイクは中止されます。
    // InsecureSkipVerify を設定することによって通常の検証が無効にされている場合,
    // または (サーバーの場合)ClientAuth が RequestClientCert または RequireAnyClientCert の場合,このコールバックは考慮されますが, VerifiedChains 引数は常に nil になります。
    VerifyPeerCertificate func(rawCerts [][]byte, verifiedChains [][]*x509.Certificate) error // Go 1.8

    // RootCAs は,クライアントがサーバー証明書を検証するときに使用する一連のルート認証局を定義します。
    // RootCAs が nil の場合, TLS はホストのルート CA セットを使用します。
    RootCAs *x509.CertPool

    // NextProtos は,サポートされているアプリケーションレベルプロトコルの優先順のリストです。
    NextProtos []string

    // InsecureSkipVerify が指定されていない限り, ServerName は返された証明書のホスト名を検証するために使用されます。
    // IP アドレスでない限り,仮想ホスティングをサポートするためにクライアントのハンドシェイクにも含まれます。
    ServerName string

    // ClientAuth は, TLS クライアント認証に対するサーバーのポリシーを決定します。
    // デフォルトは NoClientCert です。
    ClientAuth ClientAuthType

    // ClientCAs は, ClientAuth のポリシーによってクライアント証明書を検証するために必要な場合にサーバーが使用する一連のルート認証局を定義します。
    ClientCAs *x509.CertPool

    // InsecureSkipVerify は,クライアントがサーバーの証明書チェーンとホスト名を検証するかどうかを制御します。
    // InsecureSkipVerify が true の場合, TLS はサーバーによって提示されたすべての証明書とその証明書内のすべてのホスト名を受け入れます。
    // このモードでは, TLS は中間者攻撃を受けやすくなります。
    // これはテストのためだけに使われるべきです。
    InsecureSkipVerify bool

    // CipherSuites は, TLS バージョン 1.2 までの TLS バージョンでサポートされている暗号スイートのリストです。
    // CipherSuites が nil の場合,安全な暗号スイートのデフォルトリストが使用され,ハードウェアパフォーマンスに基づく優先順位が付けられます。
    // デフォルトの暗号スイートは Go のバージョンによって変わるかもしれません。
    // TLS 1.3 暗号スイートは設定できないことに注意してください。
    CipherSuites []uint16

    // PreferServerCipherSuites は,サーバーがクライアントで最も優先される暗号スイートを選択するか,サーバーで最も優先される暗号スイートを選択するかを制御します。
    // true の場合, CipherSuites の要素の順序で表されているように,サーバーの優先順位が使用されます。
    PreferServerCipherSuites bool // Go 1.1

    // セッションチケットと PSK (再開) サポートを無効にするには, SessionTicketsDisabled を true に設定します。
    // ClientSessionCache が nil の場合,クライアントではセッションチケットのサポートも無効になります。
    SessionTicketsDisabled bool // Go 1.1

    // SessionTicketKey は,セッションを再開するために TLS サーバーによって使用されます。
    // RFC 5077 および RFC 8446 の PSK モードを参照してください。
    // ゼロの場合,最初のサーバーハンドシェイクの前にランダムデータで埋められます。
    //
    // 複数のサーバーが同じホストへの接続を終了している場合,それらはすべて同じ SessionTicketKey を持つべきです。
    // SessionTicketKey がリークすると,そのキーを使用して以前に記録された TLS 接続と将来の TLS 接続が危険にさらされる可能性があります。
    SessionTicketKey [32]byte // Go 1.1

    // ClientSessionCache は, TLS セッション再開のための ClientSessionState エントリのキャッシュです。
    // クライアントによってのみ使用されます。
    ClientSessionCache ClientSessionCache // Go 1.3

    // MinVersion には,許容される最小の SSL/TLS バージョンが含まれています。
    // ゼロの場合, TLS 1.0 が最小値として扱われます。
    MinVersion uint16 // Go 1.2

    // MaxVersion には,許容される最大の SSL/TLS バージョンが含まれています。
    // 0 の場合,このパッケージでサポートされている最大バージョンが使用されます。
    // 現在は TLS 1.3 です。
    MaxVersion uint16 // Go 1.2

    // CurvePreferences には, ECDHE ハンドシェイクで使用される楕円曲線が優先順に含まれています。
    // 空の場合は,デフォルトが使用されます。
    // クライアントは, TLS 1.3 の鍵共有の型として最初の設定を使用します。
    // これは将来変わるかもしれません。
    CurvePreferences []CurveID // Go 1.3

    // DynamicRecordSizingDisabled は, TLS レコードのアダプティブサイジングを無効にします。
    // true の場合,可能な限り最大の TLS レコードサイズが常に使用されます。
    // false の場合,待ち時間を改善するために TLS レコードのサイズが調整されることがあります。
    DynamicRecordSizingDisabled bool // Go 1.7

    // Renegotiation はどの型の再ネゴシエーションがサポートされるかを制御します。
    // デフォルトの none は,大多数のアプリケーションに適しています。
    Renegotiation RenegotiationSupport // Go 1.7

    // KeyLogWriter は, Wireshark などの外部プログラムが TLS 接続を復号化できるようにするために使用できる NSS キーログ形式で TLS マスターシークレットの宛先をオプションで指定します。
    // https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Key_Log_Format を参照してください。
    // KeyLogWriter を使用するとセキュリティが低下するため,デバッグにのみ使用してください。
    KeyLogWriter io.Writer // Go 1.8
    // エクスポートされていないフィールドがあります
}

例 (KeyLogWriter)

コード:

// ネットワークトラフィックキャプチャを復号化して TLS アプリケーションをデバッグする。

// 警告 :KeyLogWriter を使用するとセキュリティが低下するため,デバッグにのみ使用してください。

// 例のための,安全でないランダムによる模擬テスト用HTTPサーバ。
server := httptest.NewUnstartedServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {}))
server.TLS = &tls.Config{
    Rand: zeroSource{}, // 例としてのみ。こうはしないでください。
}
server.StartTLS()
defer server.Close()

// 通常,ログは開いているファイルに書き込まれます。
// w, err := os.OpenFile("tls-secrets.txt", os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0600)
w := os.Stdout

client := &http.Client{
    Transport: &http.Transport{
        TLSClientConfig: &tls.Config{
            KeyLogWriter: w,

            Rand:               zeroSource{}, // 再現可能な出力用。こうはしないでください。
            InsecureSkipVerify: true,         // テストサーバー証明書は信頼されていません。
        },
    },
}
resp, err := client.Get(server.URL)
if err != nil {
    log.Fatalf("Failed to get URL: %v", err)
}
resp.Body.Close()

// 作成されたファイルは, SSL プロトコル設定で (Pre)-Master-Secret ログファイル名を設定することで, TLS 接続を復号化するために Wireshark で使用することができます。

func (*Config) BuildNameToCertificate

func (c *Config) BuildNameToCertificate()

BuildNameToCertificate は c.Certificates を解析し,各リーフ証明書の CommonName フィールドと SubjectAlternateName フィールドから c.NameToCertificate を構築します。

func (*Config) Clone 1.8

func (c *Config) Clone() *Config

Clone は c のシャロークローンを返します。 TLS クライアントまたはサーバーによって並行に使用されるConfigを複製するのは安全です。

func (*Config) SetSessionTicketKeys 1.5

func (c *Config) SetSessionTicketKeys(keys [][32]byte)

SetSessionTicketKeys は,サーバーのセッションチケットキーを更新します。 最初のキーは新しいチケットを作成するときに使用されますが,すべてのキーはチケットを復号化するために使用できます。 セッションチケットキーを回転させるために,サーバーの正常実行中にこの関数を呼び出しても安全です。 キーが空の場合,関数はパニックします。

type Conn

Conn は安全な接続を表します。 それは net.Conn インターフェースを実装します。

type Conn struct {
    // エクスポートされていないフィールドがあります
}

func Client

func Client(conn net.Conn, config *Config) *Conn

Client (クライアント) は,内部のトランスポートとして conn を使用する新しい TLS クライアント側接続を返します。 configを nil にすることはできません。 ユーザーはconfigに ServerName または InsecureSkipVerify を設定する必要があります。

func Dial

func Dial(network, addr string, config *Config) (*Conn, error)

ダイヤルは net.Dial を使用して特定のネットワークアドレスに接続してから TLS ハンドシェイクを開始し,結果の TLS 接続を返します。 Dial は,nil 設定をゼロ設定と同等と解釈します。 デフォルトについては Config のドキュメントを参照してください。

コード:

// カスタムルート証明書セットを使って接続する。

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-----`

// まず,一連のルート証明書を作成します。
// この例では 1 つしかありません。
// 現在のオペレーティングシステムのデフォルトのルートセットを使用するために,これを省略することも可能です。
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 1.3

func DialWithDialer(dialer *net.Dialer, network, addr string, config *Config) (*Conn, error)

DialWithDialer は, dialer.Dial を使用して特定のネットワークアドレスに接続してから TLS ハンドシェイクを開始し,結果の TLS 接続を返します。 ダイヤラで指定されたすべてのタイムアウトまたは期限は,全体として接続および TLS ハンドシェイクに適用されます。

DialWithDialer は, nil 構成ををゼロ構成と同等に解釈します。 デフォルトについては Config のドキュメントを参照してください。

func Server

func Server(conn net.Conn, config *Config) *Conn

Serverは,内部のトランスポートとして conn を使用する新しい TLS サーバー側接続を返します。 config設定は nil 以外でなければならず,少なくとも 1 つの証明書を含むか,そうでなければ GetCertificate を設定する必要があります。

func (*Conn) Close

func (c *Conn) Close() error

Close は接続を閉じます。

func (*Conn) CloseWrite 1.8

func (c *Conn) CloseWrite() error

CloseWrite は,接続の書き込み側をシャットダウンします。 これは,ハンドシェイクが完了したときにのみ呼び出され,内部の接続で CloseWrite を呼び出しません。 ほとんどの呼び出し元はただCloseを使うべきです。

func (*Conn) ConnectionState

func (c *Conn) ConnectionState() ConnectionState

ConnectionState は,接続に関する基本的な TLS の詳細を返します。

func (*Conn) Handshake

func (c *Conn) Handshake() error

Handshake は,まだ実行されていない場合は,クライアントまたはサーバーのハンドシェイクプロトコルを実行します。 このパッケージのほとんどの用途では Handshake を明示的に呼び出す必要はありません。 最初の Read または Write が自動的にそれを呼び出します。

func (*Conn) LocalAddr

func (c *Conn) LocalAddr() net.Addr

LocalAddr はローカルネットワークアドレスを返します。

func (*Conn) OCSPResponse

func (c *Conn) OCSPResponse() []byte

OCSPResponse は, TLS サーバーからステープル OCSP レスポンスがある場合はそれを返します。 (クライアント接続にのみ有効)

func (*Conn) Read

func (c *Conn) Read(b []byte) (int, error)

Read は,一定の制限時間の後に Timeout() == true にし net.Error を返すようにすることができます。 SetDeadline と SetReadDeadline を参照してください。

func (*Conn) RemoteAddr

func (c *Conn) RemoteAddr() net.Addr

RemoteAddr はリモートネットワークアドレスを返します。

func (*Conn) SetDeadline

func (c *Conn) SetDeadline(t time.Time) error

SetDeadline は,接続に関連付けられている読み取り期限と書き込み期限を設定します。 t の値が 0 の場合,読み取りと書き込みはタイムアウトしません。 書き込みがタイムアウトした後, TLS の状態は破損しており,それ以降のすべての書き込みで同じエラーが返されます。

func (*Conn) SetReadDeadline

func (c *Conn) SetReadDeadline(t time.Time) error

SetReadDeadline は,内部の接続に読み取り期限を設定します。 t がゼロの場合, Read はタイムアウトしません。

func (*Conn) SetWriteDeadline

func (c *Conn) SetWriteDeadline(t time.Time) error

SetWriteDeadline は,内部の接続に書き込み期限を設定します。 t がゼロの場合,書き込みはタイムアウトしません。 書き込みがタイムアウトした後, TLS の状態は破損しており,それ以降のすべての書き込みで同じエラーが返されます。

func (*Conn) VerifyHostname

func (c *Conn) VerifyHostname(host string) error

VerifyHostname は,ピア証明書チェーンがホストへの接続に有効であることを確認します。 もしそうなら,それは nil を返します。 そうでなければ,問題を説明するエラーを返します。

func (*Conn) Write

func (c *Conn) Write(b []byte) (int, error)

Write は接続にデータを書き込みます。

type ConnectionState

ConnectionState は,接続に関する基本的な TLS の詳細を記録します。

type ConnectionState struct {
    Version                     uint16                // 接続で使用されている TLS のバージョン (例 :VersionTLS12); added in Go 1.3
    HandshakeComplete           bool                  // TLS ハンドシェイクが完了しました
    DidResume                   bool                  // 接続は前の TLS 接続を再開します; added in Go 1.1
    CipherSuite                 uint16                // 使用中の暗号スイート (TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, ...)
    NegotiatedProtocol          string                // ネゴシエートされた次のプロトコル (Config.NextProtos からのものであることは保証されていません)
    NegotiatedProtocolIsMutual  bool                  // ネゴシエートされたプロトコルがサーバーによってアドバイスされました (クライアント側のみ)
    ServerName                  string                // 存在する場合 ,クライアントからリクエストされたサーバー名 (サーバー側のみ)
    PeerCertificates            []*x509.Certificate   // リモートピアによって提示された証明書チェーン
    VerifiedChains              [][]*x509.Certificate // PeerCertificates から構築された検証済みチェーン
    SignedCertificateTimestamps [][]byte              // 存在する場合,ピアからの SCT; added in Go 1.5
    OCSPResponse                []byte                // 存在する場合,ピアからのステープル OCSP 応答; added in Go 1.5

    // TLSUnique には, "tls-unique" チャンネルにバインドされている値が含まれています (RFC 5929 のセクション 3 を参照) 。
    // 再開されたセッションでは,再開に十分なコンテキストが含まれていないため,この値は nil になります https://mitls.org/pages/attacks/3SHAKE#channelbindingsを参照) 。
    // TLS マスターシークレットの修正が標準化され実装された後は, Go の将来のバージョンではこれが変わるでしょう。
    // TLS 1.3 では定義されていません。
    TLSUnique []byte // Go 1.4
    // エクスポートされていないフィールドがあります
}

func (*ConnectionState) ExportKeyingMaterial 1.11

func (cs *ConnectionState) ExportKeyingMaterial(label string, context []byte, length int) ([]byte, error)

ExportKeyingMaterial は,RFC 5705 で定義されているように,新しいスライスのエクスポートされたキーマテリアルの長さバイトを返します。 context が nil の場合,シードの一部としては使用されません。 接続が Config.Renegotiation による再ネゴシエーションを許可するように設定されている場合,この関数はエラーを返します。

type CurveID 1.3

CurveID は,楕円曲線の TLS 識別子の種類です。 https://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-8 を参照してください。

TLS 1.3 では,この型は NamedGroup と呼ばれますが,現時点ではこのライブラリは楕円曲線ベースのグループのみをサポートしています。 RFC 8446 のセクション 4.2.7 を参照してください。

type CurveID uint16
const (
    CurveP256 CurveID = 23
    CurveP384 CurveID = 24
    CurveP521 CurveID = 25
    X25519    CurveID = 29
)

type RecordHeaderError 1.6

TLS レコードヘッダが無効な場合, RecordHeaderError が返されます。

type RecordHeaderError struct {
    // Msg には,エラーを説明する人間が読める文字列が含まれています。
    Msg string
    // RecordHeader には,エラーの原因となった 5 バイトの TLS レコードヘッダーが含まれています。
    RecordHeader [5]byte
    // クライアントが TLS のように見えなかった初期ハンドシェイクを送信した場合, Conn は内部の net.Conn を提供します。
    // すでにハンドシェイクが行われている場合,または TLS アラートが接続に書き込まれている場合は無効です。
    Conn net.Conn // Go 1.12
}

func (RecordHeaderError) Error 1.6

func (e RecordHeaderError) Error() string

type RenegotiationSupport 1.7

RenegotiationSupport (再ネゴシエーションサポート) は, TLS 再ネゴシエーションに対するさまざまなレベルのサポートを列挙します。 TLS 再ネゴシエーションは,接続に対して最初のハンドシェークの後,後続のハンドシェイクを実行する行為です。 これはステートマシンを著しく複雑にし,数多くの微妙なセキュリティ問題の原因となっています。 再ネゴシエーションの開始はサポートされていませんが,再ネゴシエーションのリクエストを受け入れるためのサポートは有効になっているかもしれません。

有効にされても,サーバはハンドシェイク間でアイデンティティを変更しないかもしれません (すなわち,リーフ証明書は同じでなければなりません) 。 さらに,並行ハンドシェイクとアプリケーションデータフローは許可されていないため,再ネゴシエーションは, HTTPS などの再ネゴシエーションと同期するプロトコルでのみ使用できます。

再ネゴシエーションは TLS 1.3 では定義されていません。

type RenegotiationSupport int
const (
    // RenegotiateNever は再ネゴシエーションを無効にします。
    RenegotiateNever RenegotiationSupport = iota

    // RenegotiateOnceAsClient を使用すると,リモートサーバーは接続ごとに 1 回再ネゴシエーションをリクエストできます。
    RenegotiateOnceAsClient

    // RenegotiateFreelyAsClient を使用すると,リモートサーバーは繰り返し再ネゴシエーションをリクエストできます。
    RenegotiateFreelyAsClient
)

type SignatureScheme 1.8

SignatureScheme は, TLS でサポートされている署名アルゴリズムを識別します。 RFC 8446 のセクション 4.2.3 を参照してください。

type SignatureScheme uint16
const (
    // RSASSA-PKCS1-v1_5 アルゴリズム
    PKCS1WithSHA256 SignatureScheme = 0x0401
    PKCS1WithSHA384 SignatureScheme = 0x0501
    PKCS1WithSHA512 SignatureScheme = 0x0601

    // 公開鍵 OID rsaEncryption を使用した RSASSA-PSS アルゴリズム。
    PSSWithSHA256 SignatureScheme = 0x0804
    PSSWithSHA384 SignatureScheme = 0x0805
    PSSWithSHA512 SignatureScheme = 0x0806

    // ECDSA アルゴリズム TLS 1.3 では特定の曲線のみに制約されていました。
    ECDSAWithP256AndSHA256 SignatureScheme = 0x0403
    ECDSAWithP384AndSHA384 SignatureScheme = 0x0503
    ECDSAWithP521AndSHA512 SignatureScheme = 0x0603

    // EdDSA algorithms.
    Ed25519 SignatureScheme = 0x0807

    // TLS 1.2 用の従来の署名およびハッシュアルゴリズム。
    PKCS1WithSHA1 SignatureScheme = 0x0201
    ECDSAWithSHA1 SignatureScheme = 0x0203
)