1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109

//! [`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:
//!
//! ```ignore
//! [dependencies]
//! pipebuf_rustls = "0.23"
//! rustls = "0.23"
//! ```
//!
//! Or maybe like this to use `ring`:
//!
//! ```ignore
//! [dependencies]
//! pipebuf_rustls = "0.23"
//! rustls = { version = "0.23", features = ["ring"] }
//! ```
//!
//! Or maybe like this to disable `tls12`:
//!
//! ```ignore
//! [dependencies]
//! pipebuf_rustls = "0.23"
//! rustls = { version = "0.23", default-features = false,
//!            features = ["aws_lc_rs", "logging"] }
//! ```
//!
//! Check out the [**Rustls**
//! `Cargo.toml`](https://github.com/rustls/rustls/blob/main/rustls/Cargo.toml)
//! to see how to control this.
//!
//! To use the Rustls unbuffered implementation (not recommended yet),
//! you'll need something like this:
//!
//! ```ignore
//! [dependencies]
//! pipebuf_rustls = { version = "0.23", default-features = false, features = ["unbuffered"] }
//! rustls = "0.23"
//! ```
//!
//! [`PipeBuf`]: https://crates.io/crates/pipebuf
//! [**Rustls**]: https://crates.io/crates/rustls

#![forbid(unsafe_code)]

pub use rustls;

#[cfg(all(not(feature = "unbuffered"), not(feature = "buffered")))]
compile_error!("Select a crate feature: either `buffered` or `unbuffered`");

// If they select both `unbuffered` and `buffered`, default to
// `buffered` for 0.23, since that is more mature
#[cfg(feature = "buffered")]
mod client;
#[cfg(feature = "buffered")]
mod server;
#[cfg(feature = "buffered")]
pub use client::TlsClient;
#[cfg(feature = "buffered")]
pub use server::TlsServer;

#[cfg(not(feature = "buffered"))]
mod unbuf;
#[cfg(not(feature = "buffered"))]
pub use unbuf::{TlsClient, TlsServer};

/// Error in TLS processing
#[derive(Debug)]
pub struct TlsError(String);

impl std::error::Error for TlsError {}

impl std::fmt::Display for TlsError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", self.0)
    }
}