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.
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, thanks for the issue! As per @FiloSottile's suggestion in #40510 (comment) 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.
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!