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

[knweiss]

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]

/cc @bradfitz

[FiloSottile]

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]

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

[odeke-em]

@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.

[knweiss]

@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]

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 ***@***.***> 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 <#40510 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABFL3V7H2A3QON4SRATDGUTTC4NSHANCNFSM4PPUMPHA> .

[gopherbot]

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