crypto/x509: doc: clarify package is aimed towards Web PKI support

[adamdecaf]

It's been noted before that crypto/x509 is aimed towards only supporting the Web PKI. (See: #16858 (comment) and #24151 (comment)) However the documentation doesn't clearly state that.

This means it's a bit unclear what to expect from this package.

• Is it valid for SystemCertPool() to return certificates for email signing?
• How forgiving should parsing / validation be?
• What level of extensibility (re: OID's) should be supported?

Explaining non-goals would also be helpful.

[gopherbot]

Change https://golang.org/cl/126136 mentions this issue: crypto/x509: clarify package is for the web pki

[adamdecaf]

cc @FiloSottile

[odeke-em]

Kindly paging @FiloSottile, @agl commented on the CL, please take a look. Thank you.

[FiloSottile]

I think this would also be important in terms of ensuring the package can evolve as the PKI does. However, in practice we do support custom roots, so we can't just say "WebPKI only". What about this wording?

This package targets a profile of X.509 compatible with the WebPKI and other PKIs that follow the current CA/Browser Forum Baseline Requirements.

@sleevi, any opinions?

[sleevi]

Yeah, I can't think of any better way to frame it, especially since you support things that are not permitted by the "Web PKI" profile (e.g. URI nameConstraints). Removing support for something the Web PKI removes support for is consistent with keeping the profiles compatible, while it's clear you don't limit support to exactly that profile.

[gopherbot]

Change https://golang.org/cl/241118 mentions this issue: crypto/x509: clarify package use-case and implementation reasoning

[gopherbot]

Change https://golang.org/cl/266541 mentions this issue: crypto/x509: expand package docs and clarify package target