1use std::env;
2use std::path::{Path, PathBuf};
3
4/// The OpenSSL environment variable to configure what certificate file to use.
5pub const ENV_CERT_FILE: &'static str = "SSL_CERT_FILE";
6
7/// The OpenSSL environment variable to configure what certificates directory to use.
8pub const ENV_CERT_DIR: &'static str = "SSL_CERT_DIR";
9
10pub struct ProbeResult {
11 pub cert_file: Option<PathBuf>,
12 pub cert_dir: Option<PathBuf>,
13}
14
15/// Probe the system for the directory in which CA certificates should likely be
16/// found.
17///
18/// This will only search known system locations.
19#[doc(hidden)]
20#[deprecated(note = "use `candidate_cert_dirs` instead")]
21pub fn find_certs_dirs() -> Vec<PathBuf> {
22 candidate_cert_dirs().map(Path::to_path_buf).collect()
23}
24
25/// Probe the system for the directory in which CA certificates should likely be
26/// found.
27///
28/// This will only search known system locations.
29pub fn candidate_cert_dirs() -> impl Iterator<Item = &'static Path> {
30 // see http://gagravarr.org/writing/openssl-certs/others.shtml
31 [
32 "/var/ssl",
33 "/usr/share/ssl",
34 "/usr/local/ssl",
35 "/usr/local/openssl",
36 "/usr/local/etc/openssl",
37 "/usr/local/share",
38 "/usr/lib/ssl",
39 "/usr/ssl",
40 "/etc/openssl",
41 "/etc/pki/ca-trust/extracted/pem",
42 "/etc/pki/tls",
43 "/etc/ssl",
44 "/etc/certs",
45 "/opt/etc/ssl", // Entware
46 #[cfg(target_os = "android")]
47 "/data/data/com.termux/files/usr/etc/tls",
48 #[cfg(target_os = "haiku")]
49 "/boot/system/data/ssl",
50 ]
51 .iter()
52 .map(Path::new)
53 .filter(|p| p.exists())
54}
55
56/// Deprecated as this isn't sound, use [`init_openssl_env_vars`] instead.
57#[doc(hidden)]
58#[deprecated(note = "this function is not safe, use `init_openssl_env_vars` instead")]
59pub fn init_ssl_cert_env_vars() {
60 unsafe {
61 init_openssl_env_vars();
62 }
63}
64
65/// Probe for SSL certificates on the system, then configure the SSL certificate `SSL_CERT_FILE`
66/// and `SSL_CERT_DIR` environment variables in this process for OpenSSL to use.
67///
68/// Preconfigured values in the environment variables will not be overwritten if the paths they
69/// point to exist and are accessible.
70///
71/// # Safety
72///
73/// This function is not safe because it mutates the process's environment
74/// variables which is generally not safe. See the [documentation in libstd][doc]
75/// for information about why setting environment variables is not safe.
76///
77/// If possible use the [`probe`] function and directly configure OpenSSL
78/// methods instead of relying on environment variables.
79///
80/// [doc]: https://doc.rust-lang.org/stable/std/env/fn.set_var.html#safety
81pub unsafe fn init_openssl_env_vars() {
82 try_init_openssl_env_vars();
83}
84
85/// Deprecated as this isn't sound, use [`try_init_openssl_env_vars`] instead.
86#[doc(hidden)]
87#[deprecated(note = "use try_init_openssl_env_vars instead, this function is not safe")]
88pub fn try_init_ssl_cert_env_vars() -> bool {
89 unsafe { try_init_openssl_env_vars() }
90}
91
92/// Probe for SSL certificates on the system, then configure the SSL certificate `SSL_CERT_FILE`
93/// and `SSL_CERT_DIR` environment variables in this process for OpenSSL to use.
94///
95/// Preconfigured values in the environment variables will not be overwritten if the paths they
96/// point to exist and are accessible.
97///
98/// Returns `true` if any certificate file or directory was found while probing.
99/// Combine this with `has_ssl_cert_env_vars()` to check whether previously configured environment
100/// variables are valid.
101///
102/// # Safety
103///
104/// This function is not safe because it mutates the process's environment
105/// variables which is generally not safe. See the [documentation in libstd][doc]
106/// for information about why setting environment variables is not safe.
107///
108/// If possible use the [`probe`] function and directly configure OpenSSL
109/// methods instead of relying on environment variables.
110///
111/// [doc]: https://doc.rust-lang.org/stable/std/env/fn.set_var.html#safety
112pub unsafe fn try_init_openssl_env_vars() -> bool {
113 let ProbeResult {
114 cert_file,
115 cert_dir,
116 } = probe();
117 // we won't be overwriting existing env variables because if they're valid probe() will have
118 // returned them unchanged
119 if let Some(path) = &cert_file {
120 unsafe {
121 put(ENV_CERT_FILE, path);
122 }
123 }
124 if let Some(path) = &cert_dir {
125 unsafe {
126 put(ENV_CERT_DIR, path);
127 }
128 }
129
130 unsafe fn put(var: &str, path: &Path) {
131 // Avoid calling `setenv` if the variable already has the same contents. This avoids a
132 // crash when called from out of perl <5.38 (Debian Bookworm is at 5.36), as old versions
133 // of perl tend to manipulate the `environ` pointer directly.
134 if env::var_os(var).as_deref() != Some(path.as_os_str()) {
135 unsafe {
136 env::set_var(var, path);
137 }
138 }
139 }
140
141 cert_file.is_some() || cert_dir.is_some()
142}
143
144/// Check whether the OpenSSL `SSL_CERT_FILE` and/or `SSL_CERT_DIR` environment variable is
145/// configured in this process with an existing file or directory.
146///
147/// That being the case would indicate that certificates will be found successfully by OpenSSL.
148///
149/// Returns `true` if either variable is set to an existing file or directory.
150pub fn has_ssl_cert_env_vars() -> bool {
151 let probe: ProbeResult = probe_from_env();
152 probe.cert_file.is_some() || probe.cert_dir.is_some()
153}
154
155fn probe_from_env() -> ProbeResult {
156 let var: impl Fn(&'static str) -> Option<…> = |name: &'static str| env::var_os(key:name).map(PathBuf::from).filter(|p: &PathBuf| p.exists());
157 ProbeResult {
158 cert_file: var(ENV_CERT_FILE),
159 cert_dir: var(ENV_CERT_DIR),
160 }
161}
162
163/// Probe the current system for the "cert file" and "cert dir" variables that
164/// OpenSSL typically requires.
165///
166/// The probe result is returned as a [`ProbeResult`] structure here.
167pub fn probe() -> ProbeResult {
168 let mut result = probe_from_env();
169 for certs_dir in candidate_cert_dirs() {
170 // cert.pem looks to be an openssl 1.0.1 thing, while
171 // certs/ca-certificates.crt appears to be a 0.9.8 thing
172 let cert_filenames = [
173 "cert.pem",
174 "certs.pem",
175 "ca-bundle.pem",
176 "cacert.pem",
177 "ca-certificates.crt",
178 "certs/ca-certificates.crt",
179 "certs/ca-root-nss.crt",
180 "certs/ca-bundle.crt",
181 "CARootCertificates.pem",
182 "tls-ca-bundle.pem",
183 ];
184 if result.cert_file.is_none() {
185 result.cert_file = cert_filenames
186 .iter()
187 .map(|fname| certs_dir.join(fname))
188 .find(|p| p.exists());
189 }
190 if result.cert_dir.is_none() {
191 let cert_dir = certs_dir.join("certs");
192 if cert_dir.exists() {
193 result.cert_dir = Some(cert_dir);
194 }
195 }
196 if result.cert_file.is_some() && result.cert_dir.is_some() {
197 break;
198 }
199 }
200 result
201}
202