crypto/tls: improve documentation for ServerName.

Users of the low-level, Client function are frequenctly missing the
fact that, unless they pass a ServerName to the TLS connection then it
cannot verify the certificates against any name.

This change makes it clear that at least one of InsecureSkipVerify and
ServerName should always be set.

LGTM=bradfitz
R=golang-codereviews, bradfitz
CC=golang-codereviews
https://golang.org/cl/65440043

diff --git a/src/pkg/crypto/tls/common.go b/src/pkg/crypto/tls/common.go
index 3382853ee660a37fd43db1dbf273d7205497a6a2..7ce2077de41aaf70b3f687c63f0414e435f8bf7d 100644 (file)
--- a/src/pkg/crypto/tls/common.go
+++ b/src/pkg/crypto/tls/common.go
@@ -231,8 +231,9 @@ type Config struct {
        // NextProtos is a list of supported, application level protocols.
        NextProtos []string
 
-       // ServerName is included in the client's handshake to support virtual
-       // hosting.
+       // 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.
        ServerName string
 
        // ClientAuth determines the server's policy for

diff --git a/src/pkg/crypto/tls/tls.go b/src/pkg/crypto/tls/tls.go
index 6c67506fc3610aee314b138e7ccad5666684c46b..40156a0013bc9fb982d2cd143d57c2759232f6e7 100644 (file)
--- a/src/pkg/crypto/tls/tls.go
+++ b/src/pkg/crypto/tls/tls.go
@@ -27,9 +27,8 @@ func Server(conn net.Conn, config *Config) *Conn {
 
 // Client returns a new TLS client side connection
 // using conn as the underlying transport.
-// Client interprets a nil configuration as equivalent to
-// the zero configuration; see the documentation of Config
-// for the defaults.
+// The config cannot be nil: users must set either ServerHostname or
+// InsecureSkipVerify in the config.
 func Client(conn net.Conn, config *Config) *Conn {
        return &Conn{conn: conn, config: config, isClient: true}
 }