search

golang / go

The Go programming language
https://go.dev
BSD 3-Clause "New" or "Revised" License
124.42k stars 17.71k forks source link

net/http: the http.ServeTLS() docstring shouldn't ask for the root CA certificate #40510

Open knweiss opened 4 years ago

knweiss commented 4 years ago

Both http.ServeTLS() and http.ListenAndServeTLS() currently have the following docstring regarding the certFile argument:

"If the certificate is signed by a certificate authority, the certFile should be the concatenation of the server's certificate, any intermediates, and the CA's certificate."

I would like to suggest to change the sentence above into this:

"If the certificate is signed by a certificate authority (CA), the certFile should be the concatenation of the server's certificate and all intermediate CA certificates (if there are any). However, do not add the root CA certificate to the certFile because trust can't be introduced server-side. TLS clients will provide the root CA certificate from their root CA trust store. A TLS connection will be secure and successful if the set of certificates both from the TLS server and the TLS client forms a valid certificate chain."

IMHO more verbose language is helpful as X.509 certificates are a rather complicated topic.

@FiloSottile

cagedmantis commented 4 years ago

/cc @bradfitz

FiloSottile commented 4 years ago

I don't think we can effectively teach how TLS works in the net/http docs, but we should be clear about how to correctly use our functions. I would suggest this wording.

If the certificate is signed by a certificate authority (CA), the certFile should be the concatenation of the server's certificate and any intermediate CA certificates (but not the root CA's certificate).

knweiss commented 4 years ago

This is fine with me, too. My main point was the root CA certificate.

odeke-em commented 3 years ago

@knweiss, thanks for the issue! As per @FiloSottile's suggestion in https://github.com/golang/go/issues/40510#issuecomment-668109728 that you are fine with, would you like to send a PR or a CL per https://golang.org/doc/contribute? The Go tree for 1.17 development is currently wide open, and it would be awesome to mint a new Go contributor from you, seeing your issue from opening to change update completed.

knweiss commented 3 years ago

@odeke-em Thanks for asking but as this is only a tiny documentation change I would appreciate if somebody else with contributor rights would change it.

odeke-em commented 3 years ago

I’ll gladly help you out, but would be nice to have you as a new contributor, the steps are simple, and that’ll democratize and scale development so that in the future as you notice, and figure out things that can be changed, you can directly help out. This issue is already you creating an impact for the next Go user out there. Thank you again!

On Tue, Mar 9, 2021 at 11:28 PM Karsten Weiss notifications@github.com wrote:

@odeke-em https://github.com/odeke-em Thanks for asking but as this is only a tiny documentation change I would appreciate if somebody else with contributor rights would change it.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/golang/go/issues/40510#issuecomment-795017998, or unsubscribe https://github.com/notifications/unsubscribe-auth/ABFL3V7H2A3QON4SRATDGUTTC4NSHANCNFSM4PPUMPHA .

gopherbot commented 3 years ago

Change https://golang.org/cl/311789 mentions this issue: net/http: clarify that certFile doesn't require the root CA's certificate