PipeBuf wrapper for Rustls

This offers a single "process" call that takes care of all the calls required to move data between the encrypted and plain-text sides of a Rustls ServerConnection, transferring data via pipe-buffers. This would typically be used along with other PipeBuf-supporting crates such as pipebuf_mio to offer transport, along with a PipeBuf-based implementation of the wrapped protocol to form a complete processing chain.

Documentation

See the crate documentation.

License

This project is licensed under either the Apache License version 2 or the MIT license, at your option. (See LICENSE-APACHE and LICENSE-MIT).

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

lib.rs:

PipeBuf wrapper around Rustls

This offers a single "process" call that takes care of all the calls required to move data between the encrypted and plain-text sides of a Rustls client or server connection structure. This would typically be used along with other PipeBuf-supporting crates such as pipebuf_mio or similar to offer transport, and a PipeBuf-based implementation of the wrapped protocol to form a complete solution.

Internally this uses either the buffered or unbuffered interface provided by Rustls, depending on which cargo feature is selected. The default is to use the buffered interface because that is mature. Whilst the unbuffered interface mostly works as of 0.23.4, there are some rough corners (some failing tests in this crate) and it doesn't yet offer any performance advantage due to the planned Rustls unbuffered optimisations not yet being implemented.

Versioning

This crate follows the major/minor version number of the Rustls crate it wraps. Rustls is re-exported as pipebuf_rustls::rustls.

Selecting Rustls crate features

This crate brings in Rustls with only std enabled by default (for buffered operation). This means that you need to include the same version of Rustls in your own dependencies in order to select the features required, especially the crypto provider. This approach is necessary in order to allow you to use default-features = false to disable tls12 if necessary. So your dependency section may look like this to use the default crypto provider:

[dependencies]
pipebuf_rustls = "0.23"
rustls = "0.23"

Or maybe like this to use ring:

[dependencies]
pipebuf_rustls = "0.23"
rustls = { version = "0.23", features = ["ring"] }

Or maybe like this to disable tls12:

[dependencies]
pipebuf_rustls = "0.23"
rustls = { version = "0.23", default-features = false,
           features = ["aws_lc_rs", "logging"] }

Check out the Rustls Cargo.toml to see how to control this.

To use the Rustls unbuffered implementation (not recommended yet), you'll need something like this:

[dependencies]
pipebuf_rustls = { version = "0.23", default-features = false, features = ["unbuffered"] }
rustls = "0.23"