trillium_rustls/
lib.rs

1#![forbid(unsafe_code)]
2#![deny(
3    clippy::dbg_macro,
4    missing_copy_implementations,
5    rustdoc::missing_crate_level_docs,
6    missing_debug_implementations,
7    missing_docs,
8    nonstandard_style,
9    unused_qualifications
10)]
11
12/*!  This crate provides rustls trait implementations for trillium client ([`RustlsConnector`]) and
13server ([`RustlsAcceptor`]).
14
15# Cargo Features
16
17This crate's default features should be appropriate for most users. To pare down on dependencies or
18customize trillium-rustls' usage of rustls, opt out of default features and reenable the appropriate
19features for your use case.
20
21## `server` and `client` features
22
23This crate offers a `server` feature and a `client` feature. Opting out of default features allows
24you to avoid building any dependencies for the unused other component. By default, both `server` and
25`client` features are enabled.
26
27## Cryptographic backend selection
28
29Rustls supports pluggable cryptographic backends as well as a process-default cryptographic
30cryptographic backend. There are two built-in feature-enabled cryptographic backends and other
31community provided cryptographic backends.
32
33⚠️ There are three cryptographic backend cargo features, and they behave differently than the rustls
34features. Please read the following section.⚠️
35
36`trillium-rustls` tries to avoid runtime panics where possible, so compiling this crate without a
37valid cryptographic backend will result in a compile time error. To opt into rustls's default
38process-default behavior, enable `custom-crypto-provider` as described below. Enabling multiple
39crypto providers will select exactly one of them at compile time in the following order:
40
41### `aws-lc-rs`
42
43This is the default cryptographic backend in concordance with rustls' default. This backend will be
44selected if the feature is enabled. If either of the other two cryptographic backends are selected,
45trillium-rustls will log an error but use `aws-lc-rs`.
46
47### `ring`
48
49If this feature is enabled, this backend will be selected even if `custom-crypto-provider` is also
50enabled.
51
52### `custom-crypto-provider`
53
54In order to use a crypto provider other than the above two options, enable the
55`custom-crypto-provider` feature and either configure a
56[`trillium_rustls::rustls::ClientConfig`][rustls::ClientConfig] or
57[`trillium_rustls::rustls::ServerConfig`][rustls::ServerConfig] yourself to convert the equivalent
58`trillium-rustls` type, or install a custom process-default crypto provider with
59[`trillium_rustls::rustls::crypto::CryptoProvider::install_default`][rustls::crypto::CryptoProvider::install_default]
60prior to executing trillium-rustls code.
61
62## Client verifier
63
64This crate offers a `platform-verifier` feature for client usage that builds a ClientConfig with the
65selected cryptographic backend and uses
66[`rustls-platform-verifier`](https://docs.rs/rustls-platform-verifier/). This feature is enabled by
67default. If you disable the feature, [`webpki_roots`] will be used.
68*/
69
70#[cfg(feature = "client")]
71mod client;
72#[cfg(feature = "client")]
73pub use client::{RustlsClientTransport, RustlsConfig};
74
75#[cfg(feature = "server")]
76mod server;
77#[cfg(feature = "server")]
78pub use server::{RustlsAcceptor, RustlsServerTransport};
79
80pub use futures_rustls;
81pub use futures_rustls::rustls;
82
83#[cfg(any(feature = "client", feature = "server"))]
84mod crypto_provider;
85pub(crate) use crypto_provider::crypto_provider;
trillium_rustls/lib.rs

trillium_rustls/
lib.rs
