crypto/tls: Documentation and/or signature of crypto/tls.Conn.VerifyHostname could be clearer

[gopherbot]

by ox@getlantern.org:

What does 'go version' print?

go version go1.3.3 darwin/amd64

What steps reproduce the problem?
If possible, include a link to a program on play.golang.org.

See this gist - https://gist.github.com/oxtoacart/e13883d91039dc44f5e6

What happened?

Function TestUsingVerifyHostname fails.

What should have happened instead?

It's actually okay that this test fails, but not intuitive.  conn.VerifyHostname doesn't
actually validate the certificate chain against the configured RootCAs.  In fact, it
doesn't really do anything with the "chain" at all, it simply checks the
peer's certificate.  Here's the code snippet from conn.go:

c.peerCertificates[0].VerifyHostname(host)

To make this clearer, I think the documentation for that function should read something
like:

"VerifyHostname checks that the peer's certificate is a valid certificate for the
named host. If so, it returns nil; if not, it returns an error describing the problem.
WARNING - VerifyHostname does not validate the peer certificate chain against any
CAs."

Perhaps even better, the function could have a signature that accepts an *x509.CertPool
called RootCAs and, if provided, actually does validate agains them.

[ianlancetaylor]

Comment 1:

Labels changed: added repo-main, release-none, documentation.

[agl]

Comment 2:

Labels changed: added release-go1.5, removed release-none.

[agl]

Comment 3:

Owner changed to @agl.

[rsc]

I checked the code and consulted @agl, and it looks like the only way c.peerCertificates[0] is not part of a verified chain is if you set InsecureSkipVerify in the TLS config. Are you doing that? If not, I think the docs are clear. And if you're setting InsecureSkipVerify, it's not too surprising that VerifyHostname does not do the "verify" part.