wolfcrypt-tls-tokio

Async TLS for tokio backed by wolfSSL. TlsStream<IO> implements tokio::io::AsyncRead + AsyncWrite.

Why

The same reasons to choose wolfcrypt-tls for blocking I/O apply here — FIPS 140-3 validation, small footprint, no OpenSSL — but for async Rust with tokio:

• FIPS 140-3 — the only async tokio TLS crate backed by a FIPS-validated crypto module (commercial license; contact wolfSSL)
• tokio-rustls-compatible API — TlsConnector / TlsAcceptor / TlsStream<IO> have the same shapes; swap the import and adjust the config builder
• No spawn_blocking — wolfSSL runs inline in the async task over in-memory buffers; one connection does not consume one OS thread

Usage

[dependencies]
wolfcrypt-tls-tokio = "0.1"
tokio = { version = "1", features = ["full"] }

TLS client

use std::sync::Arc;
use tokio::net::TcpStream;
use wolfssl_tokio::{TlsConnector, TlsClientConfig, RootCertStore};

let mut roots = RootCertStore::new();
roots.add_pem(include_bytes!("ca.pem"));

let config = Arc::new(
    TlsClientConfig::builder()
        .with_root_certificates(roots)
        .with_no_client_auth()
        .build()?,
);

let stream = TcpStream::connect("example.com:443").await?;
let mut tls = TlsConnector::from(config).connect("example.com", stream)?.await?;
tls.write_all(b"GET / HTTP/1.1\r\nHost: example.com\r\n\r\n").await?;

connect() returns Result<Connect<IO>>; the ? checks for config errors and the .await? drives the handshake to completion.

TLS server

use std::sync::Arc;
use tokio::net::TcpListener;
use wolfssl_tokio::{TlsAcceptor, TlsServerConfig, Certificate, PrivateKey};

let config = Arc::new(
    TlsServerConfig::builder()
        .with_certificate_chain(
            Certificate::from_pem(include_bytes!("server.pem")),
            PrivateKey::from_pem(include_bytes!("server-key.pem")),
        )
        .with_no_client_auth()
        .build()?,
);

let acceptor = TlsAcceptor::from(config);
let listener = TcpListener::bind("0.0.0.0:443").await?;

loop {
    let (stream, _addr) = listener.accept().await?;
    let acceptor = acceptor.clone();
    tokio::spawn(async move {
        let mut tls = acceptor.accept(stream)?.await?;
        // tls: TlsStream<TcpStream> — AsyncRead + AsyncWrite
        Ok::<_, wolfssl_tokio::Error>(())
    });
}

Mutual TLS (mTLS)

// Server — require a client certificate
let config = TlsServerConfig::builder()
    .with_certificate_chain(cert, key)
    .with_client_auth(client_ca_store)
    .build()?;

// Client — present a certificate
let config = TlsClientConfig::builder()
    .with_root_certificates(roots)
    .with_client_auth(client_cert, client_key)
    .build()?;

How it works

wolfssl-src            Compiles wolfSSL C source
      │
wolfcrypt-sys          bindgen FFI bindings
      │
wolfcrypt-tls          Config types, cert/key loading  (lib.name = "wolfssl")
      │
wolfcrypt-tls-tokio    TlsConnector / TlsAcceptor / TlsStream  ← this crate
      │
tokio                  AsyncRead, AsyncWrite, TcpStream

Instead of wolfSSL_set_fd, the crate drives wolfSSL through custom IO callbacks over two in-memory byte buffers (net_in / net_out):

                    ┌───────────────────────────────────┐
                    │         TlsStream<IO>              │
 poll_read  ◄───────┤  read_buf (decrypted plaintext)    │
 poll_write ───────►│  wolfSSL session                   │
                    │    recv_cb ◄── net_in              │
                    │    send_cb ──► net_out             │
 network IO ◄───────┤  flush net_out / fill net_in ─────►│  network IO
   (cipher)         └───────────────────────────────────┘   (cipher)

The callbacks are synchronous and never block. All real async network I/O happens in poll_read / poll_write around the wolfSSL calls — the same architecture as tokio-rustls.

Config types (TlsClientConfig, TlsServerConfig, Certificate, PrivateKey, RootCertStore, ProtocolVersion) are re-exported from wolfcrypt-tls. The wolfcrypt-tls-futures-io crate provides the same session logic for the futures::io trait family (smol, async-std).

References

• wolfcrypt-tls — blocking API and config types re-exported here
• wolfcrypt-tls-futures-io — futures::io variant of the same session logic
• tokio — async runtime providing AsyncRead / AsyncWrite and the TcpStream / TcpListener types used in the examples
• tokio-rustls — API model this crate mirrors (TlsConnector / TlsAcceptor / TlsStream<IO>)
• wolfSSL documentation
• RFC 8446 — TLS 1.3
• RFC 5246 — TLS 1.2
• workspace README

Copyright

Copyright (C) 2006-2026 wolfSSL Inc.

License

GPL-3.0-only OR LicenseRef-wolfSSL-commercial.

The underlying wolfSSL C library is licensed under GPL-3.0-or-later with a commercial option available from wolfSSL Inc.