TLS API

The TLS module provides secure socket layer support for both client and server operations.

TlsConfig

Configuration for TLS contexts.

pub const TlsConfig = struct {
    allocator: Allocator,
    min_version: TlsVersion = .tls_1_2,
    max_version: TlsVersion = .tls_1_3,
    verify_mode: VerifyMode = .peer,
    verify_hostname: bool = true,
    ca_file: ?[]const u8 = null,
    ca_path: ?[]const u8 = null,
    cert_file: ?[]const u8 = null,
    key_file: ?[]const u8 = null,
    // ALPN protocols for protocol negotiation (h2 for HTTP/2, h3 for HTTP/3).
    alpn_protocols: []const []const u8 = &.{ "http/1.1" },
    cipher_suites: ?[]const u8 = null,
    server_name: ?[]const u8 = null,
};

Methods

init

Creates a default configuration (safe defaults).

pub fn init(allocator: Allocator) Self

insecure

Creates a configuration that skips verification (useful for testing).

pub fn insecure(allocator: Allocator) Self

TlsSession

Manages a single TLS client connection over an attached TCP socket.

pub const TlsSession = struct {
    // State fields
    connected: bool,
    negotiated_protocol: ?[]const u8,
};

Methods

• attachSocket(socket: *Socket) void: Attaches a connected socket for the session transport.
• handshake(hostname: []const u8) !void: Performs the TLS handshake using std.crypto.tls.Client.
• read(buffer: []u8) !usize: Decrypts and reads data.
• write(data: []const u8) !usize: Encrypts and writes data.
• getReader() !*std.Io.Reader: Returns a reader for decrypted TLS payload.
• getWriter() !*std.Io.Writer: Returns a writer for TLS-encrypted payload.
• getAlpnProtocol() ?[]const u8: Returns the negotiated ALPN protocol (e.g., "h2" for HTTP/2, "h3" for HTTP/3).
• isHttp2() bool: Returns true if HTTP/2 was negotiated via ALPN.

Types

TlsVersion

Enum: .tls_1_0, .tls_1_1, .tls_1_2, .tls_1_3.

VerifyMode

Enum: .none, .peer, .fail_if_no_peer_cert, .client_once.