Crate tls_api

One TLS API to rule them all

Support both:

• tokio
• async-std

and four TLS implementations:

• tls-api-openssl, wraps openssl crate
• tls-api-rustls, wraps rustls crate
• tls-api-native-tls, wraps native-tls crate
• tls-api-security-framework, wraps security-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>() -> tls_api::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) -> tls_api::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 compiles
• tls-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 tokio
• runtime-async-std enables the implementation over async-std

Currently the features are mutually exclusive.

Modules

async_as_sync	Utility used in different implementations of TLS API.
runtime	Tokio or async-std type reexports.
spi	Interfaces needed by API implementor (like tls-api-rustls), and not needed by the users of API.

Macros

spi_acceptor_common	Common part of all connectors. Poor man replacement for HKT.
spi_async_socket_impl_delegate	Delegate AsyncSocket implementation to the underlying socket.
spi_connector_common	Common part of all connectors. Poor man replacement for HKT.
spi_tls_stream_over_sync_io_wrapper	Implement wrapper for TlsStreamOverSyncIo.

Structs

AsyncSocketBox	Newtype for Box<dyn AsyncSocket>.
BoxFuture	Newtype for Pin<Box<Future>> for simpler function signatures.
Error	Error returned by virtually all operations of this crate.
ImplInfo	Basic info about the implementation.
TlsAcceptorBox	Dynamic version of TlsAcceptor.
TlsAcceptorBuilderBox	Dynamic version of TlsAcceptorBuilder.
TlsConnectorBox	Configured connector. This is a dynamic version of TlsConnector.
TlsConnectorBuilderBox	TlsConnector without type parameter.
TlsStream	Similar to TlsStreamWithSocket, but without a socket type parameter.
TlsStreamWithSocket	TLS stream object returned by connect_with_socket and accept_with_socket operations.

Traits

AsyncSocket	Type alias for necessary socket async traits.
TlsAcceptor	A builder for server-side TLS connections.
TlsAcceptorBuilder	A builder for TlsAcceptors.
TlsAcceptorType	Similar to TlsAcceptor, but it is dynamic, does not require type parameter.
TlsConnector	A builder for client-side TLS connections.
TlsConnectorBuilder	A builder for TlsConnectors.
TlsConnectorType	Similar to TlsConnector, but it is dynamic, does not require type parameter.
TlsStreamDyn	Trait implemented by all TlsStream objects.
TlsStreamWithSocketDyn	Get the underlying socket.

Type Definitions

Result

A typedef of the result type returned by many methods.