proposal: crypto/x509: allow user override of the system roots on all platforms

[Snaipe]

Proposal Details

Today, Go supports on Unices (not darwin) the ability to override the system roots through the use of the environment variables SSL_CERT_FILE and SSL_CERT_DIR.

Having this ability to change the system roots without modifying the target Go binary is great for testing and integration into larger programs that invoke other Go programs. In particular, while it is trivial to modify a Go program to specify an alternate source for the system roots, not all Go programs that open TLS connections provide an option to do so.

Unfortunately, SSL_CERT_FILE and SSL_CERT_DIR are not honored on every system. This can be understandable since both are, originally, OpenSSL-specific, and Windows and macOS have their own ways to manage their system certificate store.

For these reasons, I'd like to propose a mechanism to override the system roots on platforms that do not support SSL_CERT_FILE/DIR. Today, these platforms are Windows, macOS, and Plan9 (and wasm, but that's probably not applicable?). I can mostly see two options here:

Option 1: extend SSL_CERT_FILE and SSL_CERT_DIR to other platforms.

This one is straightforward: move the logic that loads the roots from these variables out of roots_unix.go and in the SystemCertPool function.

The benefit is that quite a lot of tooling that set SSL_CERT_FILE would now work with no modification on more platforms. There is precedent in some languages/libraries doing this (Rust TLS for instance), too.

The drawback however is that this sudden support might not be desired, or lead to surprising behavior (for instance, tools that set the variable by mistake on Windows and relied on the actual system roots being loaded would suddenly honor the variable).

Option 2: introduce Go-specific environment variables GO_SSL_CERT_FILE and GO_SSL_CERT_DIR

This is less disruptive; it would mostly entail copying the code handling SSL_CERT_FILE/DIR and duplicate it into SystemCertPool, but using the environment variables GO_SSL_CERT_FILE/DIR instead. There is precedent in other languages and/or libraries doing this (NODE_EXTRA_CA_CERTS, REQUESTS_CA_BUNDLE, ...), so it wouldn't be too surprising to users.

---

Overall, option 1 would probably be the most seamless w.r.t. integration, but realistically I think the only real option is option 2 to avoid any potential breakage.

[gabyhelp]

Related Issues

• crypto/x509: Document how to make custom cert root list #6267 (closed)
• crypto/x509: documentation about SSL_CERT_FILE and SSL_CERT_DIR is incorrect #37907 (closed)
• crypto/x509: export systemRootsPool or equivilant #13335 (closed)
• proposal: x509.Certificate.Verify should provide an option for both using the host's root CA set and an additional set of user-provided root CAs #34937 (closed)
• crypto/x509: use platform verifier on Windows, macOS and iOS #46287 (closed)
• crypto/x509: add SetFallbackRoots and golang.org/x/crypto/x509roots/fallback package #43958 (closed)
• proposal: crypto/x509: support systemVerify with p11-kit #71799

Related Code Changes

• crypto/x509: rework how system roots are loaded on unix systems
• crypto/x509: load certificates from paths in env vars, extra certs dirs
• crypto/x509: load all trusted certs on darwin (cgo)

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[ianlancetaylor]

CC @golang/security