@sfackler sfackler released this Nov 6, 2016 · 1011 commits to master since this release

The 0.9 release brings many major changes.

OpenSSL version support

This crate now supports the newly released 1.1.0 version of OpenSSL. Massive
thanks to @alexcrichton for driving this forward and implementing the changes
necessary to deal with the significant API changes in OpenSSL!

OpenSSL versions 0.9.8 and 1.0.0 have reached their end of life and are no
longer receiving security updates. As a result, this crate no longer supports
linking against them.

openssl-sys changes

Version and feature detection

openssl-sys now inspects the headers in the target OpenSSL installation,
extracting the version as well as build time options. These are used to provide
FFI bindings which are accurate to that specific configuration. Functions have
been added or removed, or even changed signatures across versions. This
information is exposed by the build script so that downstream crates may
conditionally compile themselves as appropriate.

To ensure these bindings remain accurate over time, we now use the systest
crate to automatically verify that the functions, constants, and struct
definitions correctly represent their C equivalents. This process has found
several issues, including incorrect signedness, constness, and even extra
function parameters!

Build script improvements

The build script detection logic has been significantly improved. It will
automatically detect OpenSSL installed via Homebrew on OSX. If it fails to find
an installation, it will print a message explaining what steps need to be
taken. The separate OPENSSL_LIB_DIR and OPENSSL_INCLUDE_DIR environment
variables have been merged into a single OPENSSL_DIR variable. This should
minimize the likelyhood of linking against a version that does not correspond
to the headers that were detected.

The build script will output the version of OpenSSL being linked against as
well as the OpenSSL build configuration (OPENSSL_NO_COMP for example).
Downstream crates can link against openssl-sys to conditionally compile code
to support multiple versions when necessary. See openssl's build script for

Probe module

The probe module has been removed, as it does not really belong in this crate.

openssl changes

SSL configuration

OpenSSL's SSL/TLS support is a minefield; it's default configuration is highly
insecure, and it is nontrivial to turn all of the right knobs in the right
ways. New types have been added which wrap SslContext and Ssl, managing all
of that for you. You should probably never use the Ssl type directly to
create an SslStream

Clients should use the SslConnector type. Servers should use the
SslAcceptor type, which supports several configurations based off of
Mozilla's server side TLS recommendations.

Other SSL APIs

The SslContext type is now immutable. It is reference counted and shared by
all SslStreams created from it, and so mutation of it is not thread safe.
There is now an SslContextBuilder which can be used to configure it.

SslStream's constructors have been moved to methods on Ssl and the
IntoSsl trait has been removed.

The hostname verification APIs added in OpenSSL 1.0.2 have been exposed through
the Ssl::param_mut method.

SslContextBuilder::set_tmp_ecdh was added to configure the ECDH curve used by
a server.

Fatal handshake errors will contain a MidHandshakeSslStream when possible,
allowing the specific certificate validation error to be displayed in error
messages, and retrieval of other information from the Ssl.

Ssl::shutdown has been added to properly shutdown an SSL session.

Feature overhaul

The crate now only has two features - v102 and v110. They correspond to
asking for functionality exposed in OpenSSL versions 1.0.2 and 1.1.0
respectively, when the library is actually being linked against that version.
For example, the SslContextBuilder::set_ecdh_auto method will be exposed if
the v102 feature is activated and openssl-sys links against OpenSSL 1.0.2.
The Ssl::params_mut method will be exposed if either the v102 feature is
activated and openssl-sys links against OpenSSL 1.0.2, or the v110
feature is activated and openssl-sys links against OpenSSL 1.1.0.


Many enums have been converted to opaque wrapper types, including Nid,
Cipher, and SslMethod.

Ref types

All OpenSSL types have been split into two - an owned type and a reference
type, for example SslContext and SslContextRef. The owned type derefs to
the reference type, and most methods are defined on the reference type.


The Signer type can sign data with a PKey, and the Verifier type can
verify a signature against a PKey.

The hmac module and the sign and verify methods on the Dsa and Rsa
types have been removed in favor of these new APIs.


The BigNum APIs have been overhauled. In particular, a BigNumContext type
has been added, corresponding to the OpenSSL BN_CTX type. Some operations
have been moved to BigNumContext, as they require it for scratch space.


RSA encryption and decryption is now supported.

Symmetric encryption

AES GCM is now supported.


Modules previously placed under the crypto module have been moved to the
crate root.

Types have been camel-cased - RSA is now Rsa, for example.

Assets 2