GO Config用法及代码示例

GO语言"crypto/tls"包中"Config"类型的用法及代码示例。

Config 结构用于配置 TLS 客户端或服务器。在将其传递给 TLS 函数后，不得对其进行修改。一个 Config 可以被重用； tls 包也不会修改它。

用法:

type Config struct {
    // Rand provides the source of entropy for nonces and RSA blinding.
    // If Rand is nil, TLS uses the cryptographic random reader in package
    // crypto/rand.
    // The Reader must be safe for use by multiple goroutines.
    Rand io.Reader

    // Time returns the current time as the number of seconds since the epoch.
    // If Time is nil, TLS uses time.Now.
    Time func() time.Time

    // Certificates contains one or more certificate chains to present to the
    // other side of the connection.The first certificate compatible with the
    // peer's requirements is selected automatically.
    //
    // Server configurations must set one of Certificates, GetCertificate or
    // GetConfigForClient.Clients doing client-authentication may set either
    // Certificates or GetClientCertificate.
    //
    // Note: if there are multiple Certificates, and they don't have the
    // optional field Leaf set, certificate selection will incur a significant
    // per-handshake performance cost.
    Certificates []Certificate

    // NameToCertificate maps from a certificate name to an element of
    // Certificates.Note that a certificate name can be of the form
    // '*.example.com' and so doesn't have to be a domain name as such.
    //
    // Deprecated: NameToCertificate only allows associating a single
    // certificate with a given name.Leave this field nil to let the library
    // select the first compatible chain from Certificates.
    NameToCertificate map[string]*Certificate

    // GetCertificate returns a Certificate based on the given
    // ClientHelloInfo.It will only be called if the client supplies SNI
    // information or if Certificates is empty.
    //
    // If GetCertificate is nil or returns nil, then the certificate is
    // retrieved from NameToCertificate.If NameToCertificate is nil, the
    // best element of Certificates will be used.
    GetCertificate func(*ClientHelloInfo)(*Certificate, error) // Go 1.4

    // GetClientCertificate, if not nil, is called when a server requests a
    // certificate from a client.If set, the contents of Certificates will
    // be ignored.
    //
    // If GetClientCertificate returns an error, the handshake will be
    // aborted and that error will be returned.Otherwise
    // GetClientCertificate must return a non-nil Certificate.If
    // Certificate.Certificate is empty then no certificate will be sent to
    // the server.If this is unacceptable to the server then it may abort
    // the handshake.
    //
    // GetClientCertificate may be called multiple times for the same
    // connection if renegotiation occurs or if TLS 1.3 is in use.
    GetClientCertificate func(*CertificateRequestInfo)(*Certificate, error) // Go 1.8

    // GetConfigForClient, if not nil, is called after a ClientHello is
    // received from a client.It may return a non-nil Config in order to
    // change the Config that will be used to handle this connection.If
    // the returned Config is nil, the original Config will be used.The
    // Config returned by this callback may not be subsequently modified.
    //
    // If GetConfigForClient is nil, the Config passed to Server() will be
    // used for all connections.
    //
    // If SessionTicketKey was explicitly set on the returned Config, or if
    // SetSessionTicketKeys was called on the returned Config, those keys will
    // be used.Otherwise, the original Config keys will be used(and possibly
    // rotated if they are automatically managed).
    GetConfigForClient func(*ClientHelloInfo)(*Config, error) // Go 1.8

    // VerifyPeerCertificate, if not nil, is called after normal
    // certificate verification by either a TLS client or server.It
    // receives the raw ASN.1 certificates provided by the peer and also
    // any verified chains that normal processing found.If it returns a
    // non-nil error, the handshake is aborted and that error results.
    //
    // If normal verification fails then the handshake will abort before
    // considering this callback.If normal verification is disabled by
    // setting InsecureSkipVerify, or(for a server) when ClientAuth is
    // RequestClientCert or RequireAnyClientCert, then this callback will
    // be considered but the verifiedChains argument will always be nil.
    VerifyPeerCertificate func(rawCerts [][]byte, verifiedChains [][]*x509.Certificate) error // Go 1.8

    // VerifyConnection, if not nil, is called after normal certificate
    // verification and after VerifyPeerCertificate by either a TLS client
    // or server.If it returns a non-nil error, the handshake is aborted
    // and that error results.
    //
    // If normal verification fails then the handshake will abort before
    // considering this callback.This callback will run for all connections
    // regardless of InsecureSkipVerify or ClientAuth settings.
    VerifyConnection func(ConnectionState) error // Go 1.15

    // RootCAs defines the set of root certificate authorities
    // that clients use when verifying server certificates.
    // If RootCAs is nil, TLS uses the host's root CA set.
    RootCAs *x509.CertPool

    // NextProtos is a list of supported application level protocols, in
    // order of preference.If both peers support ALPN, the selected
    // protocol will be one from this list, and the connection will fail
    // if there is no mutually supported protocol.If NextProtos is empty
    // or the peer doesn't support ALPN, the connection will succeed and
    // ConnectionState.NegotiatedProtocol will be empty.
    NextProtos []string

    // ServerName is used to verify the hostname on the returned
    // certificates unless InsecureSkipVerify is given.It is also included
    // in the client's handshake to support virtual hosting unless it is
    // an IP address.
    ServerName string

    // ClientAuth determines the server's policy for
    // TLS Client Authentication.The default is NoClientCert.
    ClientAuth ClientAuthType

    // ClientCAs defines the set of root certificate authorities
    // that servers use if required to verify a client certificate
    // by the policy in ClientAuth.
    ClientCAs *x509.CertPool

    // InsecureSkipVerify controls whether a client verifies the server's
    // certificate chain and host name.If InsecureSkipVerify is true, crypto/tls
    // accepts any certificate presented by the server and any host name in that
    // certificate.In this mode, TLS is susceptible to machine-in-the-middle
    // attacks unless custom verification is used.This should be used only for
    // testing or in combination with VerifyConnection or VerifyPeerCertificate.
    InsecureSkipVerify bool

    // CipherSuites is a list of enabled TLS 1.0-1.2 cipher suites.The order of
    // the list is ignored.Note that TLS 1.3 ciphersuites are not configurable.
    //
    // If CipherSuites is nil, a safe default list is used.The default cipher
    // suites might change over time.
    CipherSuites []uint16

    // PreferServerCipherSuites is a legacy field and has no effect.
    //
    // It used to control whether the server would follow the client's or the
    // server's preference.Servers now select the best mutually supported
    // cipher suite based on logic that takes into account inferred client
    // hardware, server hardware, and security.
    //
    // Deprecated: PreferServerCipherSuites is ignored.
    PreferServerCipherSuites bool // Go 1.1

    // SessionTicketsDisabled may be set to true to disable session ticket and
    // PSK(resumption) support.Note that on clients, session ticket support is
    // also disabled if ClientSessionCache is nil.
    SessionTicketsDisabled bool // Go 1.1

    // SessionTicketKey is used by TLS servers to provide session resumption.
    // See RFC 5077 and the PSK mode of RFC 8446.If zero, it will be filled
    // with random data before the first server handshake.
    //
    // Deprecated: if this field is left at zero, session ticket keys will be
    // automatically rotated every day and dropped after seven days.For
    // customizing the rotation schedule or synchronizing servers that are
    // terminating connections for the same host, use SetSessionTicketKeys.
    SessionTicketKey [32]byte // Go 1.1

    // ClientSessionCache is a cache of ClientSessionState entries for TLS
    // session resumption.It is only used by clients.
    ClientSessionCache ClientSessionCache // Go 1.3

    // MinVersion contains the minimum TLS version that is acceptable.
    //
    // By default, TLS 1.2 is currently used as the minimum when acting as a
    // client, and TLS 1.0 when acting as a server.TLS 1.0 is the minimum
    // supported by this package, both as a client and as a server.
    //
    // The client-side default can temporarily be reverted to TLS 1.0 by
    // including the value "x509sha1=1" in the GODEBUG environment variable.
    // Note that this option will be removed in Go 1.19(but it will still be
    // possible to set this field to VersionTLS10 explicitly).
    MinVersion uint16 // Go 1.2

    // MaxVersion contains the maximum TLS version that is acceptable.
    //
    // By default, the maximum version supported by this package is used,
    // which is currently TLS 1.3.
    MaxVersion uint16 // Go 1.2

    // CurvePreferences contains the elliptic curves that will be used in
    // an ECDHE handshake, in preference order.If empty, the default will
    // be used.The client will use the first preference as the type for
    // its key share in TLS 1.3.This may change in the future.
    CurvePreferences []CurveID // Go 1.3

    // DynamicRecordSizingDisabled disables adaptive sizing of TLS records.
    // When true, the largest possible TLS record size is always used.When
    // false, the size of TLS records may be adjusted in an attempt to
    // improve latency.
    DynamicRecordSizingDisabled bool // Go 1.7

    // Renegotiation controls what types of renegotiation are supported.
    // The default, none, is correct for the vast majority of applications.
    Renegotiation RenegotiationSupport // Go 1.7

    // KeyLogWriter optionally specifies a destination for TLS master secrets
    // in NSS key log format that can be used to allow external programs
    // such as Wireshark to decrypt TLS connections.
    // See https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Key_Log_Format.
    // Use of KeyLogWriter compromises security and should only be
    // used for debugging.
    KeyLogWriter io.Writer // Go 1.8
    // contains filtered or unexported fields
}

package main

import (
	"crypto/tls"
	"log"
	"net/http"
	"net/http/httptest"
	"os"
)

// zeroSource is an io.Reader that returns an unlimited number of zero bytes.
type zeroSource struct{}

func (zeroSource) Read(b []byte) (n int, err error) {
	for i := range b {
		b[i] = 0
	}

	return len(b), nil
}

func main() {
	// Debugging TLS applications by decrypting a network traffic capture.

	// WARNING: Use of KeyLogWriter compromises security and should only be
	// used for debugging.

	// Dummy test HTTP server for the example with insecure random so output is
	// reproducible.
	server := httptest.NewUnstartedServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {}))
	server.TLS = &tls.Config{
		Rand: zeroSource{}, // for example only; don't do this.
	}
	server.StartTLS()
	defer server.Close()

	// Typically the log would go to an open file:
	// 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{}, // for reproducible output; don't do this.
				InsecureSkipVerify: true,         // test server certificate is not trusted.
			},
		},
	}
	resp, err := client.Get(server.URL)
	if err != nil {
		log.Fatalf("Failed to get URL: %v", err)
	}
	resp.Body.Close()

	// The resulting file can be used with Wireshark to decrypt the TLS
	// connection by setting (Pre)-Master-Secret log filename in SSL Protocol
	// preferences.
}

package main

import (
	"crypto/tls"
	"crypto/x509"
)

func main() {
	// VerifyConnection can be used to replace and customize connection
	// verification. This example shows a VerifyConnection implementation that
	// will be approximately equivalent to what crypto/tls does normally to
	// verify the peer's certificate.

	// Client side configuration.
	_ = &tls.Config{
		// Set InsecureSkipVerify to skip the default validation we are
		// replacing. This will not disable VerifyConnection.
		InsecureSkipVerify: true,
		VerifyConnection: func(cs tls.ConnectionState) error {
			opts := x509.VerifyOptions{
				DNSName:       cs.ServerName,
				Intermediates: x509.NewCertPool(),
			}
			for _, cert := range cs.PeerCertificates[1:] {
				opts.Intermediates.AddCert(cert)
			}
			_, err := cs.PeerCertificates[0].Verify(opts)
			return err
		},
	}

	// Server side configuration.
	_ = &tls.Config{
		// Require client certificates (or VerifyConnection will run anyway and
		// panic accessing cs.PeerCertificates[0]) but don't verify them with the
		// default verifier. This will not disable VerifyConnection.
		ClientAuth: tls.RequireAnyClientCert,
		VerifyConnection: func(cs tls.ConnectionState) error {
			opts := x509.VerifyOptions{
				DNSName:       cs.ServerName,
				Intermediates: x509.NewCertPool(),
				KeyUsages:     []x509.ExtKeyUsage{x509.ExtKeyUsageClientAuth},
			}
			for _, cert := range cs.PeerCertificates[1:] {
				opts.Intermediates.AddCert(cert)
			}
			_, err := cs.PeerCertificates[0].Verify(opts)
			return err
		},
	}

	// Note that when certificates are not handled by the default verifier
	// ConnectionState.VerifiedChains will be nil.
}