ktls-stream

Stream abstraction for implementing Linux kernel TLS (kTLS) offload.

Overview

This crate is built on top of ktls-core and provides higher-level Stream abstraction that can be used as a drop-in replacement of TcpStream (or UnixStream, etc) after setting up kTLS offload.

Usage

Setting up kTLS offload generally involves these steps:

use tokio::net::TcpStream;

// Step 0 (Optional): You may probe kernel TLS compatibility in advance
let compatibilities = ktls_stream::Compatibilities::probe().expect("failed to probe ktls compatibility");

// Step 1: Creates a `TcpStream` (or something else like `UnixStream`).
let stream = TcpStream::connect("www.example.com:443").await.expect("failed to connect");

// Step 2: Configures TLS User Level Protocol (ULP) on the socket.
if let Err(e) = ktls_stream::setup_ulp(&stream) {
    if e.is_ktls_unsupported() {
        // You can fallback to general TLS implementation (omitted here).
        ...
    } else {
        // Handle other errors (omitted here).
        ...
    }
}

// Step 3: Performs TLS handshake using your preferred TLS library over the socket.
// (omitted here) and extracts the crypto materials after handshake completion.
let (extracted_secrets, tls_session, early_data_received) = handshake(&stream, ...).await.expect("failed to perform TLS handshake");

// Step 4: Creates a `Stream` using the configured socket and crypto materials.
let mut stream = ktls_stream::Stream::new(stream, extracted_secrets, tls_session, Some(early_data_received))
    .expect("failed to create ktls stream");

// Now you can use the `Stream` as a drop-in replacement of the original `TcpStream`.
// (omitted here)

Please check ktls-tests for more examples.

Kernel Compatibility

We perform daily CI tests against the following kernel versions:

• For LTS versions, we test against the latest patch.

• Have simply tested the minimum applicable kernel version, and listed above.

  We recommend using the latest Linux kernel, at least 6.6 LTS, for better support of kTLS.

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.