Struct Context 

pub struct Context<C: TlsSession> { /* private fields */ }

The context for managing a kTLS connection.

Implementations

impl<C: TlsSession> Context<C>

pub fn new(session: C, buffer: Option<Buffer>) -> Self

Creates a new kTLS context with the given TLS session and optional buffer (can be TLS early data received from peer during handshake, or a pre-allocated buffer).

pub const fn state(&self) -> &State

Returns the current kTLS connection state.

pub const fn buffer(&self) -> &Buffer

Returns a reference to the buffer.

pub const fn buffer_mut(&mut self) -> &mut Buffer

Returns a mutable reference to the buffer.

pub fn refresh_traffic_keys<S: AsFd>(&mut self, socket: &S) -> Result<()>

Sends a TLS 1.3 key_update message to refresh a connection’s keys.

This call refreshes our encryption keys. Once the peer receives the message, it refreshes its encryption and decryption keys and sends a response. Once we receive that response, we refresh our decryption keys to match. At the end of this process, keys in both directions have been refreshed.

Notes

Note that TLS implementations (including kTLS) may enforce limits on the number of key_update messages allowed on a given connection to prevent denial of service. Therefore, this should be called sparingly.

Since the kernel will never implicitly and automatically trigger key updates according to the selected cipher suite’s cryptographic constraints, the application is responsible for calling this method as needed to maintain security.

Only Linux 6.13 or later supports TLS 1.3 rekey, see the commit, and we gate this method behind feature flag tls13-key-update. This method might return an error EBUSY, which most likely indicates that the running kernel does not support this feature.

Known Issues

Under the condition that both parties are kTLS offloaded and the server uses the Tokio asynchronous runtime, if the server initiates a KeyUpdate by calling this method and then immediately performs a read I/O operation, the program will hang (the read I/O operation returns EAGAIN but the task waker does not seem to be registered correctly). This issue needs further investigation.

Errors

• Updating the TX secret fails.
• Sending the KeyUpdate message fails.
• Setting the TX secret on the socket fails.

pub fn handle_io_error<S: AsFd>(&mut self, socket: &S, err: Error) -> Result<()>

Handles io::Errors from I/O operations on kTLS-configured sockets.

Overview

When a socket is configured with kTLS, it can be used like a normal socket for data transmission - the kernel transparently handles encryption and decryption. However, TLS control messages (e.g., TLS alerts) from peers cannot be processed automatically by the kernel, which returns EIO to notify userspace.

This method helps handle such errors appropriately:

• EIO: Attempts to process any received TLS control messages. Returns Ok(()) on success, allowing the caller to retry the operation.
• Interrupted: Indicates the operation was interrupted by a signal. Returns Ok(()), allowing the caller to retry the operation.
• WouldBlock: Indicates the operation would block (e.g., non-blocking socket). Returns Ok(()), allowing the caller to retry the operation.
• BrokenPipe: Marks the stream as closed.
• Other errors: Aborts the connection with an internal_error alert and returns the original error.

Notes

Incorrect usage of this method MAY lead to unexpected behavior.

Errors

Returns the original io::Error if it cannot be recovered from.

pub fn shutdown<S: AsFd>(&mut self, socket: &S)

Closes the read side of the kTLS connection and sends a close_notify alert to the peer.

Trait Implementations

impl<C: Debug + TlsSession> Debug for Context<C>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.