Expand description
One TLS API to rule them all
Support both:
tokio
async-std
and four TLS implementations:
tls-api-openssl
, wrapsopenssl
cratetls-api-rustls
, wrapsrustls
cratetls-api-native-tls
, wrapsnative-tls
cratetls-api-security-framework
, wrapssecurity-framework
crate
The idea is that code can be written without the knowledge of the TLS implementation used, like this:
use tls_api::{TlsConnector, TlsConnectorBuilder};
// or async_std::net::TcpStream;
use tokio::net::TcpStream;
async fn download_rust_lang_org<C: TlsConnector>() -> anyhow::Result<Vec<u8>> {
let stream = TcpStream::connect(("rust-lang.org", 443)).await?;
let mut stream = C::builder()?.build()?.connect("rust-lang.org", stream).await?;
stream.write_all(b"GET / HTTP/1.1\r\nHost: rust-lang.org\r\n\r\n").await?;
let mut buf = Vec::new();
stream.read_to_end(&mut buf).await?;
Ok(buf)
}
or the same code with dynamic connector:
use tls_api::TlsConnectorType;
// or async_std::net::TcpStream;
use tokio::net::TcpStream;
async fn download_rust_lang_org(connector_type: &dyn TlsConnectorType) -> anyhow::Result<Vec<u8>> {
let stream = TcpStream::connect(("rust-lang.org", 443)).await?;
let mut stream = connector_type.builder()?.build()?.connect("rust-lang.org", stream).await?;
stream.write_all(b"GET / HTTP/1.1\r\nHost: rust-lang.org\r\n\r\n").await?;
let mut buf = Vec::new();
stream.read_to_end(&mut buf).await?;
Ok(buf)
}
Have a look at working example invoking all implementation on GitHub.
There are also two fake implementations:
tls-api-stub
crate which returns an error on any operations, useful to check code compilestls-api-no-tls
fake implementation which returns plain sockets without TLS
The API is provided to be compatible with both tokio and async-std. Crate features:
runtime-tokio
enables the implementation over tokioruntime-async-std
enables the implementation over async-std
Currently the features are mutually exclusive.
Modules
Utility used in different implementations of TLS API.
Tokio or async-std type reexports.
Interfaces needed by API implementor (like tls-api-rustls
),
and not needed by the users of API.
Macros
Common part of all connectors. Poor man replacement for HKT.
Delegate AsyncSocket
implementation to the underlying socket.
Common part of all connectors. Poor man replacement for HKT.
Implement wrapper for TlsStreamOverSyncIo
.
Structs
Newtype for Box<dyn AsyncSocket>
.
Newtype for Pin<Box<Future>>
for simpler function signatures.
Basic info about the implementation.
Dynamic version of TlsAcceptor
.
Dynamic version of TlsAcceptorBuilder
.
Configured connector. This is a dynamic version of TlsConnector
.
TlsConnector
without type parameter.
Similar to TlsStreamWithSocket
, but without a socket type parameter.
TLS stream object returned by connect_with_socket
and accept_with_socket
operations.
Traits
Type alias for necessary socket async traits.
A builder for server-side TLS connections.
A builder for TlsAcceptor
s.
Similar to TlsAcceptor
, but it is dynamic, does not require type parameter.
A builder for client-side TLS connections.
A builder for TlsConnector
s.
Similar to TlsConnector
, but it is dynamic, does not require type parameter.
Trait implemented by all TlsStream
objects.
Get the underlying socket.