min
/
boring2
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Move README info into crate root docs 

This is more discoverable in the modern Rust world!
This commit is contained in:
Steven Fackler 2018-10-07 19:59:33 -07:00
parent 0245eee724
commit d2cc0eae2d
2 changed files with 109 additions and 183 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

183
README.md
View File

@ -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

109
openssl/src/lib.rs
View File

@ -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]