openssl_probe/
lib.rs

1use std::env;
2use std::ffi::{OsStr, OsString};
3use std::path::{Path, PathBuf};
4
5/// Probe for SSL certificates on the system, then configure the SSL certificate `SSL_CERT_FILE`
6/// and `SSL_CERT_DIR` environment variables in this process for OpenSSL to use.
7///
8/// Preconfigured values in the environment variables will not be overwritten if the paths they
9/// point to exist and are accessible.
10///
11/// Returns `true` if any certificate file or directory was found while probing.
12/// Combine this with `has_ssl_cert_env_vars()` to check whether previously configured environment
13/// variables are valid.
14///
15/// # Safety
16///
17/// This function is not safe because it mutates the process's environment
18/// variables which is generally not safe. See the [documentation in libstd][doc]
19/// for information about why setting environment variables is not safe.
20///
21/// If possible use the [`probe`] function and directly configure OpenSSL
22/// methods instead of relying on environment variables.
23///
24/// [doc]: https://doc.rust-lang.org/stable/std/env/fn.set_var.html#safety
25pub unsafe fn try_init_openssl_env_vars() -> bool {
26    let ProbeResult {
27        cert_file,
28        cert_dir,
29    } = probe();
30    // we won't be overwriting existing env variables because if they're valid probe() will have
31    // returned them unchanged
32    if let Some(path) = &cert_file {
33        unsafe {
34            put(ENV_CERT_FILE, path.as_os_str());
35        }
36    }
37
38    if !cert_dir.is_empty() {
39        let mut joined = OsString::new();
40        for (i, path) in cert_dir.iter().enumerate() {
41            if i != 0 {
42                joined.push(":");
43            }
44            joined.push(path.as_os_str());
45        }
46
47        unsafe {
48            put(ENV_CERT_DIR, &joined);
49        }
50    }
51
52    unsafe fn put(var: &str, path: &OsStr) {
53        // Avoid calling `setenv` if the variable already has the same contents. This avoids a
54        // crash when called from out of perl <5.38 (Debian Bookworm is at 5.36), as old versions
55        // of perl tend to manipulate the `environ` pointer directly.
56        if env::var_os(var).as_deref() != Some(path) {
57            unsafe {
58                env::set_var(var, path);
59            }
60        }
61    }
62
63    cert_file.is_some() || !cert_dir.is_empty()
64}
65
66/// Probe the current system for the "cert file" and "cert dir" variables that
67/// OpenSSL typically requires.
68///
69/// The probe result is returned as a [`ProbeResult`] structure here.
70pub fn probe() -> ProbeResult {
71    let mut result = ProbeResult::from_env();
72    if result.cert_file.is_none() {
73        result.cert_file =
74            CERTIFICATE_FILE_NAMES
75                .iter()
76                .find_map(|p| match Path::new(p).exists() {
77                    true => Some(PathBuf::from(p)),
78                    false => None,
79                });
80    }
81
82    for certs_dir in candidate_cert_dirs() {
83        let cert_dir = PathBuf::from(certs_dir);
84        if cert_dir.exists() {
85            result.cert_dir.push(cert_dir);
86        }
87    }
88
89    result
90}
91
92/// Probe the system for the directory in which CA certificates should likely be
93/// found.
94///
95/// This will only search known system locations.
96pub fn candidate_cert_dirs() -> impl Iterator<Item = &'static Path> {
97    CERTIFICATE_DIRS
98        .iter()
99        .map(Path::new)
100        .filter(|p| p.exists())
101}
102
103/// Check whether the OpenSSL `SSL_CERT_FILE` and/or `SSL_CERT_DIR` environment variable is
104/// configured in this process with an existing file or directory.
105///
106/// That being the case would indicate that certificates will be found successfully by OpenSSL.
107///
108/// Returns `true` if either variable is set to an existing file or directory.
109pub fn has_ssl_cert_env_vars() -> bool {
110    let probe = ProbeResult::from_env();
111    probe.cert_file.is_some() || !probe.cert_dir.is_empty()
112}
113
114pub struct ProbeResult {
115    pub cert_file: Option<PathBuf>,
116    pub cert_dir: Vec<PathBuf>,
117}
118
119impl ProbeResult {
120    fn from_env() -> ProbeResult {
121        let var = |name| env::var_os(name).map(PathBuf::from).filter(|p| p.exists());
122        ProbeResult {
123            cert_file: var(ENV_CERT_FILE),
124            cert_dir: match var(ENV_CERT_DIR) {
125                Some(p) => vec![p],
126                None => vec![],
127            },
128        }
129    }
130}
131
132// see http://gagravarr.org/writing/openssl-certs/others.shtml
133// Go's related definitions can be found here:
134// https://github.com/golang/go/tree/master/src/crypto/x509
135// Look at `root_*.go` files for platform-specific files and directories.
136
137#[cfg(target_os = "linux")]
138const CERTIFICATE_DIRS: &[&str] = &[
139    "/etc/ssl/certs",     // SLES 10, SLES 11
140    "/etc/pki/tls/certs", // Fedora, RHEL
141];
142
143#[cfg(target_os = "freebsd")]
144const CERTIFICATE_DIRS: &[&str] = &[
145    "/etc/ssl/certs",         // FreeBSD 12.2+,
146    "/usr/local/share/certs", // FreeBSD
147];
148
149#[cfg(any(target_os = "illumos", target_os = "solaris"))]
150const CERTIFICATE_DIRS: &[&str] = &["/etc/certs/CA"];
151
152#[cfg(target_os = "netbsd")]
153const CERTIFICATE_DIRS: &[&str] = &["/etc/openssl/certs"];
154
155#[cfg(target_os = "aix")]
156const CERTIFICATE_DIRS: &[&str] = &["/var/ssl/certs"];
157
158#[cfg(not(any(
159    target_os = "linux",
160    target_os = "freebsd",
161    target_os = "illumos",
162    target_os = "solaris",
163    target_os = "netbsd",
164    target_os = "aix"
165)))]
166const CERTIFICATE_DIRS: &[&str] = &["/etc/ssl/certs"];
167
168#[cfg(target_os = "linux")]
169const CERTIFICATE_FILE_NAMES: &[&str] = &[
170    "/etc/ssl/certs/ca-certificates.crt", // Debian, Ubuntu, Gentoo, Joyent SmartOS, etc.
171    "/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem", // CentOS, RHEL 7 (should come before RHEL 6)
172    "/etc/pki/tls/certs/ca-bundle.crt",                  // Fedora, RHEL 6
173    "/etc/ssl/ca-bundle.pem",                            // OpenSUSE
174    "/etc/pki/tls/cacert.pem",                           // OpenELEC (a media center Linux distro)
175    "/etc/ssl/cert.pem",                                 // Alpine Linux
176    "/opt/etc/ssl/certs/ca-certificates.crt", // Entware, https://github.com/rustls/openssl-probe/pull/21
177];
178
179#[cfg(target_os = "freebsd")]
180const CERTIFICATE_FILE_NAMES: &[&str] = &["/usr/local/etc/ssl/cert.pem"];
181
182#[cfg(target_os = "dragonfly")]
183const CERTIFICATE_FILE_NAMES: &[&str] = &["/usr/local/share/certs/ca-root-nss.crt"];
184
185#[cfg(target_os = "netbsd")]
186const CERTIFICATE_FILE_NAMES: &[&str] = &["/etc/openssl/certs/ca-certificates.crt"];
187
188#[cfg(target_os = "openbsd")]
189const CERTIFICATE_FILE_NAMES: &[&str] = &["/etc/ssl/cert.pem"];
190
191#[cfg(target_os = "solaris")] // Solaris 11.2+
192const CERTIFICATE_FILE_NAMES: &[&str] = &["/etc/certs/ca-certificates.crt"];
193
194#[cfg(target_os = "illumos")]
195const CERTIFICATE_FILE_NAMES: &[&str] = &[
196    "/etc/ssl/cacert.pem", // OmniOS, https://github.com/rustls/openssl-probe/pull/22
197    "/etc/certs/ca-certificates.crt", // OpenIndiana, https://github.com/rustls/openssl-probe/pull/22
198];
199
200#[cfg(target_os = "android")] // Termux on Android, https://github.com/rustls/openssl-probe/pull/2
201const CERTIFICATE_FILE_NAMES: &[&str] = &["/data/data/com.termux/files/usr/etc/tls/cert.pem"];
202
203#[cfg(target_os = "haiku")] // https://github.com/rustls/openssl-probe/pull/4
204const CERTIFICATE_FILE_NAMES: &[&str] = &["/boot/system/data/ssl/CARootCertificates.pem"];
205
206#[cfg(not(any(
207    target_os = "linux",
208    target_os = "freebsd",
209    target_os = "dragonfly",
210    target_os = "netbsd",
211    target_os = "openbsd",
212    target_os = "solaris",
213    target_os = "illumos",
214    target_os = "android",
215    target_os = "haiku",
216)))]
217const CERTIFICATE_FILE_NAMES: &[&str] = &["/etc/ssl/certs/ca-certificates.crt"];
218
219/// The OpenSSL environment variable to configure what certificate file to use.
220pub const ENV_CERT_FILE: &'static str = "SSL_CERT_FILE";
221
222/// The OpenSSL environment variable to configure what certificates directory to use.
223pub const ENV_CERT_DIR: &'static str = "SSL_CERT_DIR";
openssl_probe/lib.rs

openssl_probe/
lib.rs
