Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
knweiss opened this issue Jul 31, 2020 · 7 comments
Labels
Documentation NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Milestone

Comments

@knweiss
Copy link

knweiss commented Jul 31, 2020

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 cagedmantis changed the title The http.ServeTLS() docstring shouldn't ask for the root CA certificate net/http: the http.ServeTLS() docstring shouldn't ask for the root CA certificate Jul 31, 2020
@cagedmantis cagedmantis added this to the Backlog milestone Jul 31, 2020
@cagedmantis cagedmantis added NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. Documentation labels Jul 31, 2020
@cagedmantis
Copy link
Contributor

/cc @bradfitz

@FiloSottile
Copy link
Contributor

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
Copy link
Author

knweiss commented Aug 3, 2020

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

@odeke-em
Copy link
Member

odeke-em commented Mar 7, 2021

@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
Copy link
Author

knweiss commented Mar 10, 2021

@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
Copy link
Member

odeke-em commented Mar 10, 2021 via email

@gopherbot
Copy link

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Documentation NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Projects
None yet
Development

No branches or pull requests

5 participants