/rust/registry/src/index.crates.io-1949cf8c6b5b557f/openssl-0.10.62/src/lib.rs

Source
//! Bindings to OpenSSL
//!
//! This crate provides a safe interface to the popular OpenSSL cryptography library. OpenSSL versions 1.0.1 through
//! 3.x.x and LibreSSL versions 2.5 through 3.7.x are supported.
//!
//! # Building
//!
//! Both OpenSSL libraries and headers are required to build this crate. There are multiple options available to locate
//! OpenSSL.
//!
//! ## Vendored
//!
//! If the `vendored` Cargo feature is enabled, the `openssl-src` crate will be used to compile and statically link to
//! a copy of OpenSSL. The build process requires a C compiler, perl (and perl-core), and make. The OpenSSL version will generally track
//! the newest OpenSSL release, and changes to the version are *not* considered breaking changes.
//!
//! ```toml
//! [dependencies]
//! openssl = { version = "0.10", features = ["vendored"] }
//! ```
//!
//! The vendored copy will not be configured to automatically find the system's root certificates, but the
//! `openssl-probe` crate can be used to do that instead.
//!
//! ## Automatic
//!
//! The `openssl-sys` crate will automatically detect OpenSSL installations via Homebrew on macOS and vcpkg on Windows.
//! Additionally, it will use `pkg-config` on Unix-like systems to find the system installation.
//!
//! ```not_rust
//! # macOS (Homebrew)
//! $ brew install openssl@3
//!
//! # macOS (MacPorts)
//! $ sudo port install openssl
//!
//! # macOS (pkgsrc)
//! $ sudo pkgin install openssl
//!
//! # Arch Linux
//! $ sudo pacman -S pkg-config openssl
//!
//! # Debian and Ubuntu
//! $ sudo apt-get install pkg-config libssl-dev
//!
//! # Fedora
//! $ sudo dnf install pkg-config perl-FindBin openssl-devel
//!
//! # Alpine Linux
//! $ apk add pkgconfig openssl-dev
//!
//! # openSUSE
//! $ sudo zypper in libopenssl-devel
//! ```
//!
//! ## Manual
//!
//! A set of environment variables can be used to point `openssl-sys` towards an OpenSSL installation. They will
//! override the automatic detection logic.
//!
//! * `OPENSSL_DIR` - If specified, the directory of an OpenSSL installation. The directory should contain `lib` and
//!     `include` subdirectories containing the libraries and headers respectively.
//! * `OPENSSL_LIB_DIR` and `OPENSSL_INCLUDE_DIR` - If specified, the directories containing the OpenSSL libraries and
//!     headers respectively. This can be used if the OpenSSL installation is split in a nonstandard directory layout.
//! * `OPENSSL_STATIC` - If set, the crate will statically link to OpenSSL rather than dynamically link.
//! * `OPENSSL_LIBS` - If set, a `:`-separated list of library names to link to (e.g. `ssl:crypto`). This can be used
//!     if nonstandard library names were used for whatever reason.
//! * `OPENSSL_NO_VENDOR` - If set, always find OpenSSL in the system, even if the `vendored` feature is enabled.
//!
//! Additionally, these variables can be prefixed with the upper-cased target architecture (e.g.
//!     `X86_64_UNKNOWN_LINUX_GNU_OPENSSL_DIR`), which can be useful when cross compiling.
//!
//! # Feature Detection
//!
//! APIs have been added to and removed from the various supported OpenSSL versions, and this library exposes the
//! functionality available in the version being linked against. This means that methods, constants, and even modules
//! will be present when building against one version of OpenSSL but not when building against another! APIs will
//! document any version-specific availability restrictions.
//!
//! A build script can be used to detect the OpenSSL or LibreSSL version at compile time if needed. The `openssl-sys`
//! crate propagates the version via the `DEP_OPENSSL_VERSION_NUMBER` and `DEP_OPENSSL_LIBRESSL_VERSION_NUMBER`
//! environment variables to build scripts. The version format is a hex-encoding of the OpenSSL release version:
//! `0xMNNFFPPS`. For example, version 1.0.2g's encoding is `0x1_00_02_07_0`.
//!
//! For example, let's say we want to adjust the TLSv1.3 cipher suites used by a client, but also want to compile
//! against OpenSSL versions that don't support TLSv1.3:
//!
//! Cargo.toml:
//!
//! ```toml
//! [dependencies]
//! openssl-sys = "0.9"
//! openssl = "0.10"
//! ```
//!
//! build.rs:
//!
//! ```
//! use std::env;
//!
//! fn main() {
//!     if let Ok(v) = env::var("DEP_OPENSSL_VERSION_NUMBER") {
//!         let version = u64::from_str_radix(&v, 16).unwrap();
//!
//!         if version >= 0x1_01_01_00_0 {
//!             println!("cargo:rustc-cfg=openssl111");
//!         }
//!     }
//! }
//! ```
//!
//! lib.rs:
//!
//! ```
//! use openssl::ssl::{SslConnector, SslMethod};
//!
//! let mut ctx = SslConnector::builder(SslMethod::tls()).unwrap();
//!
//! // set_ciphersuites was added in OpenSSL 1.1.1, so we can only call it when linking against that version
//! #[cfg(openssl111)]
//! ctx.set_ciphersuites("TLS_AES_256_GCM_SHA384:TLS_AES_128_GCM_SHA256").unwrap();
//! ```
#![doc(html_root_url = "https://docs.rs/openssl/0.10")]
#![warn(rust_2018_idioms)]
#![allow(clippy::uninlined_format_args, clippy::needless_doctest_main)]

#[doc(inline)]
pub use ffi::init;

use libc::c_int;
#[cfg(ossl300)]
use libc::c_long;

use crate::error::ErrorStack;

#[macro_use]
mod macros;

mod bio;
#[macro_use]
mod util;
pub mod aes;
pub mod asn1;
pub mod base64;
pub mod bn;
pub mod cipher;
pub mod cipher_ctx;
#[cfg(all(not(libressl), not(osslconf = "OPENSSL_NO_CMS")))]
pub mod cms;
pub mod conf;
pub mod derive;
pub mod dh;
pub mod dsa;
pub mod ec;
pub mod ecdsa;
pub mod encrypt;
#[cfg(not(boringssl))]
pub mod envelope;
pub mod error;
pub mod ex_data;
#[cfg(not(any(libressl, ossl300)))]
pub mod fips;
pub mod hash;
#[cfg(ossl300)]
pub mod lib_ctx;
pub mod md;
pub mod md_ctx;
pub mod memcmp;
pub mod nid;
#[cfg(not(osslconf = "OPENSSL_NO_OCSP"))]
pub mod ocsp;
pub mod pkcs12;
pub mod pkcs5;
#[cfg(not(boringssl))]
pub mod pkcs7;
pub mod pkey;
pub mod pkey_ctx;
#[cfg(ossl300)]
pub mod provider;
pub mod rand;
pub mod rsa;
pub mod sha;
pub mod sign;
pub mod srtp;
pub mod ssl;
pub mod stack;
pub mod string;
pub mod symm;
pub mod version;
pub mod x509;

#[cfg(boringssl)]
type LenType = libc::size_t;
#[cfg(not(boringssl))]
type LenType = libc::c_int;

#[cfg(boringssl)]
type SLenType = libc::ssize_t;
#[cfg(not(boringssl))]
type SLenType = libc::c_int;

#[inline]
fn cvt_p<T>(r: *mut T) -> Result<*mut T, ErrorStack> {
    if r.is_null() {
        Err(ErrorStack::get())
    } else {
        Ok(r)
    }
}

#[inline]
fn cvt_p_const<T>(r: *const T) -> Result<*const T, ErrorStack> {
    if r.is_null() {
        Err(ErrorStack::get())
    } else {
        Ok(r)
    }
}

#[inline]
fn cvt(r: c_int) -> Result<c_int, ErrorStack> {
    if r <= 0 {
        Err(ErrorStack::get())
    } else {
        Ok(r)
    }
}

// cvt_long is currently only used in functions that require openssl >= 3.0.0,
// so this cfg statement is used to avoid "unused function" errors when
// compiling with openssl < 3.0.0
#[inline]
#[cfg(ossl300)]
fn cvt_long(r: c_long) -> Result<c_long, ErrorStack> {
    if r <= 0 {
        Err(ErrorStack::get())
    } else {
        Ok(r)
    }
}

#[inline]
fn cvt_n(r: c_int) -> Result<c_int, ErrorStack> {
    if r < 0 {
        Err(ErrorStack::get())
    } else {
        Ok(r)
    }
}

Coverage Report

Created: 2025-12-12 07:07

Line	Count	Source
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 not be configured to automatically find the system's root certificates, but the
23		//! `openssl-probe` crate can be used to do that instead.
24		//!
25		//! ## Automatic
26		//!
27		//! The `openssl-sys` crate will automatically detect OpenSSL installations via Homebrew on macOS and vcpkg on Windows.
28		//! Additionally, it will use `pkg-config` on Unix-like systems to find the system installation.
29		//!
30		//! ```not_rust
31		//! # macOS (Homebrew)
32		//! $ brew install openssl@3
33		//!
34		//! # macOS (MacPorts)
35		//! $ sudo port install openssl
36		//!
37		//! # macOS (pkgsrc)
38		//! $ sudo pkgin install openssl
39		//!
40		//! # Arch Linux
41		//! $ sudo pacman -S pkg-config openssl
42		//!
43		//! # Debian and Ubuntu
44		//! $ sudo apt-get install pkg-config libssl-dev
45		//!
46		//! # Fedora
47		//! $ sudo dnf install pkg-config perl-FindBin openssl-devel
48		//!
49		//! # Alpine Linux
50		//! $ apk add pkgconfig openssl-dev
51		//!
52		//! # openSUSE
53		//! $ sudo zypper in libopenssl-devel
54		//! ```
55		//!
56		//! ## Manual
57		//!
58		//! A set of environment variables can be used to point `openssl-sys` towards an OpenSSL installation. They will
59		//! override the automatic detection logic.
60		//!
61		//! * `OPENSSL_DIR` - If specified, the directory of an OpenSSL installation. The directory should contain `lib` and
62		//! `include` subdirectories containing the libraries and headers respectively.
63		//! * `OPENSSL_LIB_DIR` and `OPENSSL_INCLUDE_DIR` - If specified, the directories containing the OpenSSL libraries and
64		//! headers respectively. This can be used if the OpenSSL installation is split in a nonstandard directory layout.
65		//! * `OPENSSL_STATIC` - If set, the crate will statically link to OpenSSL rather than dynamically link.
66		//! * `OPENSSL_LIBS` - If set, a `:`-separated list of library names to link to (e.g. `ssl:crypto`). This can be used
67		//! if nonstandard library names were used for whatever reason.
68		//! * `OPENSSL_NO_VENDOR` - If set, always find OpenSSL in the system, even if the `vendored` feature is enabled.
69		//!
70		//! Additionally, these variables can be prefixed with the upper-cased target architecture (e.g.
71		//! `X86_64_UNKNOWN_LINUX_GNU_OPENSSL_DIR`), which can be useful when cross compiling.
72		//!
73		//! # Feature Detection
74		//!
75		//! APIs have been added to and removed from the various supported OpenSSL versions, and this library exposes the
76		//! functionality available in the version being linked against. This means that methods, constants, and even modules
77		//! will be present when building against one version of OpenSSL but not when building against another! APIs will
78		//! document any version-specific availability restrictions.
79		//!
80		//! A build script can be used to detect the OpenSSL or LibreSSL version at compile time if needed. The `openssl-sys`
81		//! crate propagates the version via the `DEP_OPENSSL_VERSION_NUMBER` and `DEP_OPENSSL_LIBRESSL_VERSION_NUMBER`
82		//! environment variables to build scripts. The version format is a hex-encoding of the OpenSSL release version:
83		//! `0xMNNFFPPS`. For example, version 1.0.2g's encoding is `0x1_00_02_07_0`.
84		//!
85		//! For example, let's say we want to adjust the TLSv1.3 cipher suites used by a client, but also want to compile
86		//! against OpenSSL versions that don't support TLSv1.3:
87		//!
88		//! Cargo.toml:
89		//!
90		//! ```toml
91		//! [dependencies]
92		//! openssl-sys = "0.9"
93		//! openssl = "0.10"
94		//! ```
95		//!
96		//! build.rs:
97		//!
98		//! ```
99		//! use std::env;
100		//!
101		//! fn main() {
102		//! if let Ok(v) = env::var("DEP_OPENSSL_VERSION_NUMBER") {
103		//! let version = u64::from_str_radix(&v, 16).unwrap();
104		//!
105		//! if version >= 0x1_01_01_00_0 {
106		//! println!("cargo:rustc-cfg=openssl111");
107		//! }
108		//! }
109		//! }
110		//! ```
111		//!
112		//! lib.rs:
113		//!
114		//! ```
115		//! use openssl::ssl::{SslConnector, SslMethod};
116		//!
117		//! let mut ctx = SslConnector::builder(SslMethod::tls()).unwrap();
118		//!
119		//! // set_ciphersuites was added in OpenSSL 1.1.1, so we can only call it when linking against that version
120		//! #[cfg(openssl111)]
121		//! ctx.set_ciphersuites("TLS_AES_256_GCM_SHA384:TLS_AES_128_GCM_SHA256").unwrap();
122		//! ```
123		#![doc(html_root_url = "https://docs.rs/openssl/0.10")]
124		#![warn(rust_2018_idioms)]
125		#![allow(clippy::uninlined_format_args, clippy::needless_doctest_main)]
126
127		#[doc(inline)]
128		pub use ffi::init;
129
130		use libc::c_int;
131		#[cfg(ossl300)]
132		use libc::c_long;
133
134		use crate::error::ErrorStack;
135
136		#[macro_use]
137		mod macros;
138
139		mod bio;
140		#[macro_use]
141		mod util;
142		pub mod aes;
143		pub mod asn1;
144		pub mod base64;
145		pub mod bn;
146		pub mod cipher;
147		pub mod cipher_ctx;
148		#[cfg(all(not(libressl), not(osslconf = "OPENSSL_NO_CMS")))]
149		pub mod cms;
150		pub mod conf;
151		pub mod derive;
152		pub mod dh;
153		pub mod dsa;
154		pub mod ec;
155		pub mod ecdsa;
156		pub mod encrypt;
157		#[cfg(not(boringssl))]
158		pub mod envelope;
159		pub mod error;
160		pub mod ex_data;
161		#[cfg(not(any(libressl, ossl300)))]
162		pub mod fips;
163		pub mod hash;
164		#[cfg(ossl300)]
165		pub mod lib_ctx;
166		pub mod md;
167		pub mod md_ctx;
168		pub mod memcmp;
169		pub mod nid;
170		#[cfg(not(osslconf = "OPENSSL_NO_OCSP"))]
171		pub mod ocsp;
172		pub mod pkcs12;
173		pub mod pkcs5;
174		#[cfg(not(boringssl))]
175		pub mod pkcs7;
176		pub mod pkey;
177		pub mod pkey_ctx;
178		#[cfg(ossl300)]
179		pub mod provider;
180		pub mod rand;
181		pub mod rsa;
182		pub mod sha;
183		pub mod sign;
184		pub mod srtp;
185		pub mod ssl;
186		pub mod stack;
187		pub mod string;
188		pub mod symm;
189		pub mod version;
190		pub mod x509;
191
192		#[cfg(boringssl)]
193		type LenType = libc::size_t;
194		#[cfg(not(boringssl))]
195		type LenType = libc::c_int;
196
197		#[cfg(boringssl)]
198		type SLenType = libc::ssize_t;
199		#[cfg(not(boringssl))]
200		type SLenType = libc::c_int;
201
202		#[inline]
203	0	fn cvt_p<T>(r: mut T) -> Result<mut T, ErrorStack> {
204	0	if r.is_null() {
205	0	Err(ErrorStack::get())
206		} else {
207	0	Ok(r)
208		}
209	0	} Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::ssl::SSL_SESSION> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::types::SSL> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::types::SSL_CTX> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::x509v3::GENERAL_NAME> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::asn1::ASN1_TYPE> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::x509::X509_REVOKED> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::x509::X509_EXTENSION> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::x509::stack_st_X509_EXTENSION> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::x509::X509_CRL> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::x509::X509_REQ> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::types::ASN1_STRING> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::types::X509_STORE_CTX> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::types::X509> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::types::X509_NAME> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::safestack::stack_st_OPENSSL_STRING> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::types::BN_CTX> Unexecuted instantiation: openssl::cvt_p::<core::ffi::c_void> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::types::EVP_PKEY> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::types::EVP_PKEY_CTX> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::types::PKCS8_PRIV_KEY_INFO> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::types::RSA> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::types::X509_VERIFY_PARAM> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::ec::ECDSA_SIG> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::x509::stack_st_X509> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::pkcs7::PKCS7> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::types::EVP_MD_CTX> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::cms::CMS_ContentInfo> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::pkcs12::PKCS12> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::stack::OPENSSL_STACK> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::ec::EC_GROUP> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::ec::EC_POINT> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::types::CONF> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::types::EC_KEY> Unexecuted instantiation: openssl::cvt_p::<i8> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::types::EVP_CIPHER_CTX> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::types::BIO> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::dsa::DSA_SIG> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::ocsp::OCSP_CERTID> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::ocsp::OCSP_ONEREQ> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::ocsp::OCSP_REQUEST> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::ocsp::OCSP_BASICRESP> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::types::OCSP_RESPONSE> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::types::DSA> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::types::X509_STORE> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::types::ASN1_OBJECT> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::types::ASN1_INTEGER> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::types::ASN1_OCTET_STRING> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::types::BIGNUM> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::types::ASN1_TIME> Unexecuted instantiation: openssl::cvt_p::<openssl_sys::openssl::handwritten::types::DH>
210
211		#[inline]
212	0	fn cvt_p_const<T>(r: const T) -> Result<const T, ErrorStack> {
213	0	if r.is_null() {
214	0	Err(ErrorStack::get())
215		} else {
216	0	Ok(r)
217		}
218	0	}
219
220		#[inline]
221	0	fn cvt(r: c_int) -> Result<c_int, ErrorStack> {
222	0	if r <= 0 {
223	0	Err(ErrorStack::get())
224		} else {
225	0	Ok(r)
226		}
227	0	}
228
229		// cvt_long is currently only used in functions that require openssl >= 3.0.0,
230		// so this cfg statement is used to avoid "unused function" errors when
231		// compiling with openssl < 3.0.0
232		#[inline]
233		#[cfg(ossl300)]
234		fn cvt_long(r: c_long) -> Result<c_long, ErrorStack> {
235		if r <= 0 {
236		Err(ErrorStack::get())
237		} else {
238		Ok(r)
239		}
240		}
241
242		#[inline]
243	0	fn cvt_n(r: c_int) -> Result<c_int, ErrorStack> {
244	0	if r < 0 {
245	0	Err(ErrorStack::get())
246		} else {
247	0	Ok(r)
248		}
249	0	}