# portable-rustls - a fork of upstream rustls
<p align="center">☆ ☆ ☆ (a modern TLS library IMPLEMENTED IN RUST) ☆ ☆ ☆</p>
[](https://crates.io/crates/portable-rustls)
[](https://docs.rs/portable-rustls/)
__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`:
>
>```rust,ignore
>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](ROADMAP.md) for our future plans. We also have [benchmarks](BENCHMARKING.md) 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](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`:
```rust,ignore
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][aws-lc-rs-platforms-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][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.
[ring-target-platforms]: https://github.com/briansmith/ring/blob/2e8363b433fa3b3962c877d9ed2e9145612f3160/include/ring-core/target.h#L18-L64
[`crypto::CryptoProvider`]: https://docs.rs/portable-rustls/latest/portable_rustls/crypto/struct.CryptoProvider.html
[`ring`]: https://crates.io/crates/ring
[aws-lc-rs-platforms-faq]: https://aws.github.io/aws-lc-rs/faq.html#can-i-run-aws-lc-rs-on-x-platform-or-architecture
[`aws-lc-rs`]: https://crates.io/crates/aws-lc-rs
### 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.
[`rustls-mbedtls-provider`]: https://github.com/fortanix/rustls-mbedtls-provider
[`mbedtls`]: https://github.com/Mbed-TLS/mbedtls
[`rustls-openssl`]: https://github.com/tofay/rustls-openssl
[OpenSSL]: https://openssl-library.org/
[`rustls-symcrypt`]: https://github.com/microsoft/rustls-symcrypt
[SymCrypt]: https://github.com/microsoft/SymCrypt
[`boring-rustls-provider`]: https://github.com/janrueth/boring-rustls-provider
[`boringssl`]: https://github.com/google/boringssl
[`rustls-rustcrypto`]: https://github.com/RustCrypto/rustls-rustcrypto
[`RustCrypto`]: https://github.com/RustCrypto
[`rustls-wolfcrypt-provider`]: https://github.com/wolfSSL/rustls-wolfcrypt-provider
[`wolfCrypt`]: https://www.wolfssl.com/products/wolfcrypt
#### 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:
>```rust,ignore
>rustls = { package = "portable-rustls", features=[...], ... }
>```
See the [Making a custom CryptoProvider] section of the documentation for more information
on this topic.
[`custom provider example`]: https://github.com/brody4hire/portable-rustls/tree/main-develop-head/provider-example/
[`RustCrypto`]: https://github.com/RustCrypto
[Making a custom CryptoProvider]: https://docs.rs/portable-rustls/latest/portable_rustls/crypto/struct.CryptoProvider.html#making-a-custom-cryptoprovider
# 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.
[examples]: examples/
[`stream::Stream`]: https://docs.rs/portable-rustls/latest/portable_rustls/struct.Stream.html
[`mio`]: https://docs.rs/mio/latest/mio/
[`tokio-rustls`]: https://docs.rs/tokio-rustls/latest/tokio_rustls/
## 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 &
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](https://www.rust-lang.org/policies/code-of-conduct).
PLEASE REPORT PRIVATELY TO A MAINTAINER OF THIS FORK IN CASE OF ANY QUESTIONS, COMMENTS, OR POSSIBLE MISCONDUCT.