diff --git a/README.md b/README.md index 5ca291e1..9d4a8225 100644 --- a/README.md +++ b/README.md @@ -4,189 +4,6 @@ [Documentation](https://docs.rs/openssl). -## Warning - -This README does not correspond to rust-openssl 0.7.x or 0.8.x. See -[here](https://github.com/sfackler/rust-openssl/blob/b8fb29db5c246175a096260eacca38180cd77dd0/README.md) -for that README. - -## Building - -rust-openssl depends on OpenSSL version 1.0.1 or above, or LibreSSL. Both the -libraries and headers need to be present in the build environment before this -crate is compiled, and some instructions of how to do this are in the sections -below. - -### Vendored - -```toml -[dependencies] -openssl = { version = "0.10", features = ["vendored"] } -``` - -If the `vendored` Cargo feature is enabled, the `openssl-src` crate will be used -to compile OpenSSL from source and statically link to it. OpenSSL version 1.1.0 -is currently used, but that will be upgraded to 1.1.1 at some point after it is -released *without* a major version bump to this crate. - -This 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. - -### Linux - -On Linux, you can typically install OpenSSL via your package manager. The -headers are sometimes provided in a separate package than the runtime libraries -- look for something like `openssl-devel` or `libssl-dev`. You will also need the -regular development utilities, like `pkg-config`, as the custom build script relies -on them. - -```bash -# On Debian and Ubuntu -sudo apt-get install pkg-config libssl-dev -# On Arch Linux -sudo pacman -S openssl -# On Fedora -sudo dnf install openssl-devel -``` - -If installation via a package manager is not possible, or if you're cross -compiling to a separate target, you'll typically need to compile OpenSSL from -source. That can normally be done with: - -``` -curl -O https://www.openssl.org/source/openssl-1.1.0g.tar.gz -tar xf openssl-1.1.0g.tar.gz -cd openssl-1.1.0g -export CC=... -./Configure --prefix=... linux-x86_64 -fPIC -make -j$(nproc) -make install -``` - -### macOS - -Although OpenSSL 0.9.8 is preinstalled on macOS this library is being phased out -of macOS and this crate also does not support that version of OpenSSL. To use this -crate on macOS you'll need to install OpenSSL via some alternate means, typically -Homebrew: - -```bash -brew install openssl -``` - -Occasionally an update of XCode or macOS will cause the linker to fail after compilation, to rectify this you may want to try and run: - -```bash -xcode-select --install -``` - -If you're using latest version of Homebrew which supports `--prefix` command, -OpenSSL will be automatically detected. - -### Windows MSVC - -On MSVC it's unfortunately not always a trivial process acquiring OpenSSL. A couple of possibilities -are downloading precompiled binaries for OpenSSL 1.1.0, or installing OpenSSL 1.0.2 using vcpkg. - -#### Installing OpenSSL 1.1.0 using precompiled binaries - -Perhaps the easiest way to do this right now is to download [precompiled -binaries] and install them on your system. Currently it's recommended to -install the 1.1.0 (non-light) installation if you're choosing this route. - -[precompiled binaries]: http://slproweb.com/products/Win32OpenSSL.html - -Once a precompiled binary is installed you can configure this crate to find the -installation via an environment variable: - -``` -set OPENSSL_DIR=C:\OpenSSL-Win64 -``` - -During the installation process if you select "Copy OpenSSL DLLs to: The OpenSSL binaries (/bin) -directory", you will need to add them to the `PATH` environment variable: - -``` -set PATH=%PATH%;C:\OpenSSL-Win64\bin -``` - -Now you will need to [install root certificates.](#acquiring-root-certificates) - -#### Installing OpenSSL 1.0.2 using vcpkg - -Install [vcpkg](https://github.com/Microsoft/vcpkg), and install the OpenSSL port like this: - -```Batchfile -vcpkg install openssl:x64-windows -set VCPKG_ROOT=c:\path\to\vcpkg\installation -cargo build -``` - -For more information see the vcpkg build helper [documentation](http://docs.rs/vcpkg). -To finish setting up OpenSSL you will need to [install root certificates.](#acquiring-root-certificates) - -#### Acquiring Root Certificates - -Neither of the above OpenSSL distributions ship with any root certificates. -So to make requests to servers on the internet, you have to install them -manually. Download the [cacert.pem file from here], copy it somewhere safe -(`C:\OpenSSL-Win64\certs` is a good place) and point the `SSL_CERT_FILE` -environment variable there: - -``` -set SSL_CERT_FILE=C:\OpenSSL-Win64\certs\cacert.pem -``` - -[cacert.pem file from here]: https://curl.haxx.se/docs/caextract.html - -After that, you're just a `cargo build` away! - -### Windows GNU (MinGW) - -The easiest way to acquire OpenSSL when working with MinGW is to ensure you're -using [MSYS2](http://msys2.github.io) and to then execute: - -``` -# 32-bit -pacman -S mingw-w64-i686-openssl - -# 64-bit -pacman -S mingw-w64-x86_64-openssl -``` - -And after that, a `cargo build` should be all you need! - -### Manual configuration - -rust-openssl's build script will by default attempt to locate OpenSSL via -pkg-config or other system-specific mechanisms. This will not work in some -situations however, for example cross compiling or when using a copy of OpenSSL -other than the normal system install. - -The build script can be configured via environment variables: - -* `OPENSSL_DIR` - If specified, a directory that will be used to find - OpenSSL installation. It's expected that under this directory the `include` - folder has header files and a `lib` folder has the runtime libraries. -* `OPENSSL_LIB_DIR` - If specified, a directory that will be used to find - OpenSSL libraries. Overrides the `lib` folder implied by `OPENSSL_DIR` - (if specified). -* `OPENSSL_INCLUDE_DIR` - If specified, a directory that will be used to find - OpenSSL header files. Overrides the `include` folder implied by `OPENSSL_DIR` - (if specified). -* `OPENSSL_STATIC` - If specified, OpenSSL libraries will be statically rather - than dynamically linked. -* `OPENSSL_LIBS` - If specified, the names of the OpenSSL libraries that will be - linked, e.g. `ssl:crypto`. - -If `OPENSSL_DIR` or `OPENSSL_LIB_DIR` and `OPENSSL_INCLUDE_DIR` is specified, -then the build script will skip the pkg-config step. - -For target-specific configuration, each of these environment variables can be -prefixed by an upper-cased target, for example, -`X86_64_UNKNOWN_LINUX_GNU_OPENSSL_DIR`. This can be useful in cross compilation -contexts. - ### Contribution Unless you explicitly state otherwise, any contribution intentionally diff --git a/openssl/src/lib.rs b/openssl/src/lib.rs index e6455482..8c4b91bb 100644 --- a/openssl/src/lib.rs +++ b/openssl/src/lib.rs @@ -1,3 +1,112 @@ +//! Bindings to OpenSSL +//! +//! This crate provides a safe interface to the popular OpenSSL cryptography library. OpenSSL versions 1.0.1 through +//! 1.1.1 and LibreSSL versions 2.5 through 2.8 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 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", feature = ["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 +//! $ brew install openssl@1.1 +//! +//! # 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 openssl-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. +//! +//! 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")] #[macro_use]