1//! Bindings to OpenSSL
2//!
3//! This crate provides a safe interface to the popular OpenSSL cryptography library. OpenSSL versions 1.0.1 through
4//! 3.x.x and LibreSSL versions 2.5 through 3.7.x are supported.
5//!
6//! # Building
7//!
8//! Both OpenSSL libraries and headers are required to build this crate. There are multiple options available to locate
9//! OpenSSL.
10//!
11//! ## Vendored
12//!
13//! If the `vendored` Cargo feature is enabled, the `openssl-src` crate will be used to compile and statically link to
14//! a copy of OpenSSL. The build process requires a C compiler, perl (and perl-core), and make. The OpenSSL version will generally track
15//! the newest OpenSSL release, and changes to the version are *not* considered breaking changes.
16//!
17//! ```toml
18//! [dependencies]
19//! openssl = { version = "0.10", features = ["vendored"] }
20//! ```
21//!
22//! The vendored copy will be configured to automatically find a configuration and root certificates at `/usr/local/ssl`.
23//! This path can be overridden with an environment variable (see the manual section below).
24//! Alternatively, the `openssl-probe` crate can be used to find root certificates at runtime.
25//!
26//! ## Automatic
27//!
28//! The `openssl-sys` crate will automatically detect OpenSSL installations via Homebrew on macOS and vcpkg on Windows.
29//! Additionally, it will use `pkg-config` on Unix-like systems to find the system installation.
30//!
31//! ```not_rust
32//! # macOS (Homebrew)
33//! $ brew install openssl@3
34//!
35//! # macOS (MacPorts)
36//! $ sudo port install openssl
37//!
38//! # macOS (pkgsrc)
39//! $ sudo pkgin install openssl
40//!
41//! # Arch Linux
42//! $ sudo pacman -S pkgconf openssl
43//!
44//! # Debian and Ubuntu
45//! $ sudo apt-get install pkg-config libssl-dev
46//!
47//! # Fedora
48//! $ sudo dnf install pkgconf perl-FindBin perl-IPC-Cmd openssl-devel
49//!
50//! # Alpine Linux
51//! $ apk add pkgconf openssl-dev
52//!
53//! # openSUSE
54//! $ sudo zypper in libopenssl-devel
55//! ```
56//!
57//! ## Manual
58//!
59//! A set of environment variables can be used to point `openssl-sys` towards an OpenSSL installation. They will
60//! override the automatic detection logic.
61//!
62//! * `OPENSSL_DIR` - If specified, the directory of an OpenSSL installation. The directory should contain `lib` and
63//! `include` subdirectories containing the libraries and headers respectively.
64//! * `OPENSSL_LIB_DIR` and `OPENSSL_INCLUDE_DIR` - If specified, the directories containing the OpenSSL libraries and
65//! headers respectively. This can be used if the OpenSSL installation is split in a nonstandard directory layout.
66//! * `OPENSSL_STATIC` - If set, the crate will statically link to OpenSSL rather than dynamically link.
67//! * `OPENSSL_LIBS` - If set, a `:`-separated list of library names to link to (e.g. `ssl:crypto`). This can be used
68//! if nonstandard library names were used for whatever reason.
69//! * `OPENSSL_NO_VENDOR` - If set, always find OpenSSL in the system, even if the `vendored` feature is enabled.
70//!
71//! If the `vendored` Cargo feature is enabled, the following environment variable can also be used to further configure
72//! the OpenSSL build.
73//!
74//! * `OPENSSL_CONFIG_DIR` - If set, the copy of OpenSSL built by the `openssl-src` crate will be configured to look for
75//! configuration files and root certificates in this directory.
76//!
77//! Additionally, these variables can be prefixed with the upper-cased target architecture (e.g.
78//! `X86_64_UNKNOWN_LINUX_GNU_OPENSSL_DIR`), which can be useful when cross compiling.
79//!
80//! # Feature Detection
81//!
82//! APIs have been added to and removed from the various supported OpenSSL versions, and this library exposes the
83//! functionality available in the version being linked against. This means that methods, constants, and even modules
84//! will be present when building against one version of OpenSSL but not when building against another! APIs will
85//! document any version-specific availability restrictions.
86//!
87//! A build script can be used to detect the OpenSSL or LibreSSL version at compile time if needed. The `openssl-sys`
88//! crate propagates the version via the `DEP_OPENSSL_VERSION_NUMBER` and `DEP_OPENSSL_LIBRESSL_VERSION_NUMBER`
89//! environment variables to build scripts. The version format is a hex-encoding of the OpenSSL release version:
90//! `0xMNNFFPPS`. For example, version 1.0.2g's encoding is `0x1_00_02_07_0`.
91//!
92//! For example, let's say we want to adjust the TLSv1.3 cipher suites used by a client, but also want to compile
93//! against OpenSSL versions that don't support TLSv1.3:
94//!
95//! Cargo.toml:
96//!
97//! ```toml
98//! [dependencies]
99//! openssl-sys = "0.9"
100//! openssl = "0.10"
101//! ```
102//!
103//! build.rs:
104//!
105//! ```
106//! use std::env;
107//!
108//! fn main() {
109//! if let Ok(v) = env::var("DEP_OPENSSL_VERSION_NUMBER") {
110//! let version = u64::from_str_radix(&v, 16).unwrap();
111//!
112//! if version >= 0x1_01_01_00_0 {
113//! println!("cargo:rustc-cfg=openssl111");
114//! }
115//! }
116//! }
117//! ```
118//!
119//! lib.rs:
120//!
121//! ```
122//! use openssl::ssl::{SslConnector, SslMethod};
123//!
124//! let mut ctx = SslConnector::builder(SslMethod::tls()).unwrap();
125//!
126//! // set_ciphersuites was added in OpenSSL 1.1.1, so we can only call it when linking against that version
127//! #[cfg(openssl111)]
128//! ctx.set_ciphersuites("TLS_AES_256_GCM_SHA384:TLS_AES_128_GCM_SHA256").unwrap();
129//! ```
130#![doc(html_root_url = "https://docs.rs/openssl/0.10")]
131#![warn(rust_2018_idioms)]
132#![allow(clippy::uninlined_format_args, clippy::needless_doctest_main)]
133
134#[doc(inline)]
135pub use ffi::init;
136
137use libc::c_int;
138#[cfg(ossl300)]
139use libc::c_long;
140
141use crate::error::ErrorStack;
142
143#[macro_use]
144mod macros;
145
146mod bio;
147#[macro_use]
148mod util;
149pub mod aes;
150pub mod asn1;
151pub mod base64;
152pub mod bn;
153pub mod cipher;
154pub mod cipher_ctx;
155#[cfg(all(not(libressl), not(osslconf = "OPENSSL_NO_CMS")))]
156pub mod cms;
157pub mod conf;
158pub mod derive;
159pub mod dh;
160pub mod dsa;
161pub mod ec;
162pub mod ecdsa;
163pub mod encrypt;
164#[cfg(not(any(boringssl, awslc)))]
165pub mod envelope;
166pub mod error;
167pub mod ex_data;
168#[cfg(not(any(libressl, ossl300)))]
169pub mod fips;
170pub mod hash;
171pub mod kdf;
172#[cfg(ossl300)]
173pub mod lib_ctx;
174pub mod md;
175pub mod md_ctx;
176pub mod memcmp;
177pub mod nid;
178#[cfg(not(osslconf = "OPENSSL_NO_OCSP"))]
179pub mod ocsp;
180pub mod pkcs12;
181pub mod pkcs5;
182#[cfg(not(any(boringssl, awslc)))]
183pub mod pkcs7;
184pub mod pkey;
185pub mod pkey_ctx;
186#[cfg(ossl300)]
187pub mod provider;
188pub mod rand;
189pub mod rsa;
190pub mod sha;
191pub mod sign;
192pub mod srtp;
193pub mod ssl;
194pub mod stack;
195pub mod string;
196pub mod symm;
197pub mod version;
198pub mod x509;
199
200#[cfg(any(boringssl, awslc))]
201type LenType = libc::size_t;
202#[cfg(not(any(boringssl, awslc)))]
203type LenType = libc::c_int;
204
205#[cfg(any(boringssl, awslc))]
206type SLenType = libc::ssize_t;
207#[cfg(not(any(boringssl, awslc)))]
208type SLenType = libc::c_int;
209
210#[inline]
211fn cvt_p<T>(r: *mut T) -> Result<*mut T, ErrorStack> {
212 if r.is_null() {
213 Err(ErrorStack::get())
214 } else {
215 Ok(r)
216 }
217}
218
219#[inline]
220fn cvt_p_const<T>(r: *const T) -> Result<*const T, ErrorStack> {
221 if r.is_null() {
222 Err(ErrorStack::get())
223 } else {
224 Ok(r)
225 }
226}
227
228#[inline]
229fn cvt(r: c_int) -> Result<c_int, ErrorStack> {
230 if r <= 0 {
231 Err(ErrorStack::get())
232 } else {
233 Ok(r)
234 }
235}
236
237// cvt_long is currently only used in functions that require openssl >= 3.0.0,
238// so this cfg statement is used to avoid "unused function" errors when
239// compiling with openssl < 3.0.0
240#[inline]
241#[cfg(ossl300)]
242fn cvt_long(r: c_long) -> Result<c_long, ErrorStack> {
243 if r <= 0 {
244 Err(ErrorStack::get())
245 } else {
246 Ok(r)
247 }
248}
249
250#[inline]
251fn cvt_n(r: c_int) -> Result<c_int, ErrorStack> {
252 if r < 0 {
253 Err(ErrorStack::get())
254 } else {
255 Ok(r)
256 }
257}
258