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_2::{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_2::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 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.

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.