portable-rustls - a fork of upstream rustls

☆ ☆ ☆ (a modern TLS library IMPLEMENTED IN RUST) ☆ ☆ ☆

IMPORTANT NOTICE: regardless of upstream rustls project this fork is NOT CERTIFIED and NOT PEER-REVIEWED - USE AT YOUR OWN RISK (as stated further below)

RECOMMENDED USAGE OF THIS FORK (as stated further below):

Add dependency on this fork as follows in Cargo.toml:

rustls = { package = "portable-rustls", features=[...], ... }

Then import and use rustls in the code as usual.

(Unlike the original rustls, no features are enabled by default in this fork.)

NOTE: This fork supports building for targets with no atomic ptr - see info further below.

ADDITIONAL NOTE (as stated further below): FIPS support is REMOVED FROM THIS FORK; any possible vestiges remaining should be considered non-functional.

Status

FROM UPSTREAM RUSTLS:

Rustls is used in production at many organizations and projects. We aim to maintain reasonable API surface stability but the API may evolve as we make changes to accommodate new features or performance improvements.

We have a roadmap for our future plans. We also have benchmarks to prevent performance regressions and to let you evaluate rustls on your target hardware.

If you'd like to help out, please see CONTRIBUTING.md.

Changelog

The detailed list of changes in each release can be found in: https://github.com/brody4hire/portable-rustls/releases

Documentation

https://docs.rs/portable-rustls/

Approach

IMPORTANT NOTICE: regardless of upstream rustls project this fork is NOT CERTIFIED and NOT PEER-REVIEWED - USE AT YOUR OWN RISK

RECOMMENDED USAGE

RECOMMENDED USAGE OF THIS FORK:

Add dependency on this fork as follows in Cargo.toml:

rustls = { package = "portable-rustls", features=[...], ... }

Then import and use rustls in the code as usual.

(Unlike the original rustls, no features are enabled by default in this fork.)

targets with no atomic ptr

This fork supports using Arc from portable-atomic-util to support targets with no atomic ptr, with the following requirements:

Must use Rust nightly toolchain.

Must use the following cfg flags in RUSTFLAGS FOR cargo build (etc.):

• --cfg portable_atomic_unstable_coerce_unsized
• --cfg unstable_portable_atomic_arc

WHEN BUILDING FOR A TARGET WITH NO ATOMIC PTR, NEED TO ADD THE FOLLOWING DEPENDENCIES WITH SPECIFIC FEATURES ENABLED:

• add once_cell with portable-atomic feature enabled
• add portable-atomic with critical-section or unsafe-assume-single-core feature enabled - see the following for more info & requirements: https://docs.rs/portable-atomic/latest/portable_atomic/#optional-features
• possibly more requirements in case of portable-atomic with critical-section for no-std: https://docs.rs/critical-section/latest/critical_section/#usage-in-no-std-binaries

ALSO NEED TO BUILD WITH A CRYPTO PROVIDER FOR THIS CRATE TO BE USEFUL IN GENERAL.

Additional notes

FIPS support feature is removed from this fork. Any possible vestiges remaining in the API or documentation should be considered non-functional.

General usage

NOTE: Most of the general usage information below comes directly from the upstream rustls project.

Any major discrepancies from upstream rustls are noted in bold or with ALL CAPS.

Platform support

While Rustls itself is platform independent, there are some additional platform requirements for the built-in providers.

aws-lc-rs is commonly used as the provider that implements the cryptography in TLS. See the aws-lc-rs FAQ for more details of the platform/architecture support constraints in aws-lc-rs.

ring is also available via the ring crate feature: see the supported ring target platforms.

By providing a custom instance of the crypto::CryptoProvider struct, you can replace all cryptography dependencies of rustls. This is a route to being portable to a wider set of architectures and environments, or compliance requirements. See the crypto::CryptoProvider documentation for more details.

Cryptography providers

NOTICE: It is required to choose the provider of the cryptographic primitives that this library uses in this fork.

This be done by selecting the default provider (see the crypto::CryptoProvider documentation) or MORE DYNAMICALLY...

Users that wish to customize the provider in use MORE DYNAMICALLY can do so when constructing ClientConfig and ServerConfig instances using the with_crypto_provider method on the respective config builder types. See the crypto::CryptoProvider documentation for more details.

Built-in providers

Rustls ships with two built-in providers controlled by associated crate features, which are both optional in this fork:

• aws-lc-rs - available with the aws-lc-rs crate feature enabled.
• ring - available with the ring crate feature enabled.

See the documentation for crypto::CryptoProvider for details on how providers are selected.

Third-party providers

NOTICE: ANY THIRD-PARTY PROVIDER WOULD NEED TO BE ADAPTED TO WORK DIRECTLY WITH THIS FORK OF RUSTLS.

The community has also started developing third-party providers for Rustls:

• rustls-mbedtls-provider - a provider that uses mbedtls for cryptography.
• rustls-openssl - a provider that uses OpenSSL for cryptography.
• boring-rustls-provider - a work-in-progress provider that uses boringssl for cryptography.
• rustls-rustcrypto - an experimental provider that uses the crypto primitives from RustCrypto for cryptography.
• rustls-symcrypt - a provider that uses Microsoft's SymCrypt library.
• rustls-wolfcrypt-provider - a work-in-progress provider that uses wolfCrypt for cryptography.

Custom provider

There is a simple example of writing your own provider in the custom provider example. This example implements a minimal provider using parts of the RustCrypto ecosystem.

As described above, it is (highly) recommended to add dependency on this fork as follows in Cargo.toml as done in the custom provider example in this fork:

rustls = { package = "portable-rustls", features=[...], ... }

See the Making a custom CryptoProvider section of the documentation for more information on this topic.

Example code

Our examples directory contains demos that show how to handle I/O using the stream::Stream helper, as well as more complex asynchronous I/O using mio. If you're already using Tokio for an async runtime you may prefer to use tokio-rustls instead of interacting with rustls directly.

NOTE: SOME REFERENCES MAY NEED ADAPTATION TO WORK WITH THIS FORK

ADDITIONAL NOTE: tokio-rustls WOULD NEED TO BE ADAPTED TO WORK WITH THIS FORK.

The mio based examples are the most complete, and discussed below. Users new to Rustls may prefer to look at the simple client/server examples before diving in to the more complex MIO examples.

Client example program

The MIO client example program is named tlsclient-mio.

Some sample runs:

$ cargo run --bin tlsclient-mio -- --http mozilla-modern.badssl.com
HTTP/1.1 200 OK
Server: nginx/1.6.2 (Ubuntu)
Date: Wed, 01 Jun 2016 18:44:00 GMT
Content-Type: text/html
Content-Length: 644
(...)

or

$ cargo run --bin tlsclient-mio -- --http expired.badssl.com
TLS error: InvalidCertificate(Expired)
Connection closed

Run cargo run --bin tlsclient-mio -- --help for more options.

Server example program

The MIO server example program is named tlsserver-mio.

Here's a sample run; we start a TLS echo server, then connect to it with openssl and tlsclient-mio:

$ cargo run --bin tlsserver-mio -- --certs test-ca/rsa-2048/end.fullchain --key test-ca/rsa-2048/end.key -p 8443 echo &
$ echo hello world | openssl s_client -ign_eof -quiet -connect localhost:8443
depth=2 CN = ponytown RSA CA
verify error:num=19:self signed certificate in certificate chain
hello world
^C
$ echo hello world | cargo run --bin tlsclient-mio -- --cafile test-ca/rsa-2048/ca.cert --port 8443 localhost
hello world
^C

Run cargo run --bin tlsserver-mio -- --help for more options.

License

Rustls is distributed under the following three licenses:

• Apache License version 2.0.
• MIT license.
• ISC license.

These are included as LICENSE-APACHE, LICENSE-MIT and LICENSE-ISC respectively. You may use this software under the terms of any of these licenses, at your option.

Code of conduct

This project adopts the Rust Code of Conduct.

PLEASE REPORT PRIVATELY TO A MAINTAINER OF THIS FORK IN CASE OF ANY QUESTIONS, COMMENTS, OR POSSIBLE MISCONDUCT.