rustls-native-certs

The crate supports Windows, macOS, and Linux. The discovery logic follows these rules:

1. Environment Variable: On all platforms, the SSL_CERT_FILE environment variable is checked first. If set, certificates are loaded from the specified path. If the path is invalid, an error is returned.
2. Windows: Certificates are loaded from the system certificate store using the schannel crate.
3. macOS: Certificates are loaded from the keychain (merging user, admin, and system trust settings) using the security-framework crate.
4. Linux/UNIX-like: The openssl-probe crate is used to discover the filename of the system CA bundle.

The rustls-native-certs crate allows a rustls client to use the host platform's native certificate store.

Important Recommendation: The maintainers suggest using rustls-platform-verifier instead, as it provides a more robust solution and a simpler API. rustls-native-certs is primarily maintained for use within the platform verifier on platforms where no other solution is available.

To load certificates, call load_native_certs(). Note that this function can be expensive (e.g., loading and parsing a ~300KB file on some platforms), so you should call it sparingly.

// Use this function to get a snapshot of the root certificates on the platform
let certs = rustls_native_certs::load_native_certs().expect("failed to load native certs");

The load_native_certs function is the primary entry point for this crate. It returns a CertificateResult containing a vector of certificates loaded from the platform's native store.

Signature: pub fn load_native_certs() -> CertificateResult

Returns: CertificateResult containing certs: Vec<CertificateDer<'static>> representing a snapshot of the root certificates found on the platform, along with any platform-specific errors.

If certificates are not being loaded as expected, verify the following:

1. Format: Ensure certificates are in valid PEM format.
2. Headers: The -----BEGIN CERTIFICATE----- line must start with exactly five hyphens (-----).
3. Footers: The -----END CERTIFICATE----- line must end with exactly five hyphens (-----).
4. Line Breaks: Ensure there is a line break after the certificate block.

Note that the parser attempts to skip invalid sections of a file, so a malformed certificate might be silently ignored without triggering an error in the CertificateResult.

Use load_native_certs() to retrieve a collection of certificates from the platform's native certificate store. This is useful for configuring a rustls::RootCertStore when operating as a TLS client.

Note: This function can be expensive as it may involve loading and parsing large files from disk. It is recommended to call it sparingly.

If the SSL_CERT_FILE or SSL_CERT_DIR environment variables are set, the function will load certificates from those locations instead of the platform's native store.

let mut roots = rustls::RootCertStore::empty();
for cert in rustls_native_certs::load_native_certs().expect("could not load platform certs") {
    roots.add(cert).unwrap();
}

The load_native_certs() and load_certs_from_paths() functions return a CertificateResult struct. This struct contains both the successfully loaded certificates and any errors encountered during the process.

To quickly access the certificates and panic if any errors occurred, you can use the following methods:

• expect(msg: &str): Returns the certificates if errors is empty; otherwise, panics with the provided message and the list of errors.
• unwrap(): Returns the certificates if errors is empty; otherwise, panics.

let certs = rustls_native_certs::load_native_certs().expect("Failed to load certs");

If you need to load certificates from specific files or directories rather than the platform store or environment variables, use load_certs_from_paths(file: Option<&Path>, dir: Option<&Path>).

• If file is provided, certificates are loaded from that specific file.
• If dir is provided, all files within that directory are loaded.
• If both are provided, the file is used and the dir is also processed.
• All certificates must be in PEM format.
• The function handles deduplication and sorts the resulting certificates.

// Example loading from a specific file and directory
let result = rustls_native_certs::load_certs_from_paths(
    Some(Path::new("path/to/cert.pem")),
    Some(Path::new("path/to/certs_dir")),
);

You can override the platform's native certificate store by setting the following environment variables:

Important: If either (or both) of these variables are set, the library will only load certificates from these locations and will ignore the platform's native certificate store.