tls

tape
import tls from "tls";

tls is TLS 1.3 (RFC 8446), a client and a server, that never touches a socket, a clock or a random source. Each is an engine: you feed it the bytes your transport received, send the bytes it gives you, and read and write plaintext through it. The time and 64 random bytes come in with its configuration. So the same engine runs over OS sockets, over a kernel’s own network stack, over a pipe, or in memory in a test. Most of this page is the client; the server has the same shape.

A Client or a Server is a tls.Engine in that role: the engine does everything both roles do (moving bytes, reading and writing, inspecting, wiping), and c.engine reaches it. The client and the server add only what differs: start, phase and failed_in, and the server’s certificate choice. So code that only moves bytes takes a *tls.Engine and serves either end.

tape
var c: tls.Client;                       // one connection, about 53 KiB
c.start(&cfg) or { return; };            // the ClientHello is now in c.engine.output()
let e: *tls.Engine = &c.engine;
while (!e.is_connected()) {
    send(e.output());                    // your transport
    e.advance_output(e.output().len);
    let n: i64 = receive(buf[0..4096]);  // your transport
    e.feed(buf[0..n]) or { return; };    // the alert to send is in e.output()
}

It checks the server’s certificate chain with x509 against the roots you trust (usually ca_roots) and the server name you asked for, verifies the server’s signature and Finished, and protects every record with an AEAD from crypto. There is no way to skip the server’s authentication: a pinned certificate (below) replaces the chain, nothing replaces both.

What it supports: TLS 1.3 only (a TLS 1.2 server is refused); the suites TLS_AES_128_GCM_SHA256, TLS_AES_256_GCM_SHA384 and TLS_CHACHA20_POLY1305_SHA256; X25519, and P-256 when the server asks for it with a HelloRetryRequest; server signatures by ECDSA P-256/SHA-256, ECDSA P-384/SHA-384 and RSA-PSS with SHA-256/384/512; ALPN; KeyUpdate both ways. Not: resumption, 0-RTT, client certificates (a server that asks gets an empty Certificate).

The module is pure and works in every profile, t0 included: it allocates nothing; all its buffers are inside the Engine of a Client or Server. In a hosted program the net module drives it over sockets for you (tls_connect, tls_accept); use tls directly for other transports or your own event loop.

Configuration

tape
pub struct Config {
    server_name: []const u8;         // host name or IP address literal
    trust: ?*const x509.TrustStore;  // the roots to trust; null only with a pin
    now_unix: i64;                   // seconds since 1970 UTC
    entropy: []const u8;             // ENTROPY_LEN (64) random bytes
    alpn: []const []const u8 = [];   // protocols to offer, preferred first
    pin_leaf_sha256: []const u8 = [];   // the SHA-256 of the one leaf to accept
}

pub const ENTROPY_LEN: i64 = 64;
pub const MAX_ALPN: i64 = 256;
  • server_name is sent to the server as SNI (unless it is an IP address) and checked against the certificate’s subjectAltName.
  • trust is read when the server’s certificate arrives; keep it alive and unchanged while the client runs.
  • now_unix decides whether the certificates are in their validity period. A wrong clock makes good certificates fail, never bad ones pass.
  • entropy must be 64 bytes from a real random source (os.random_bytes); the engine draws its keys and its ClientHello random from them. Never reuse them.
  • alpn is the Application-Layer Protocol Negotiation list, such as "h2" and "http/1.1"; the encoded list is at most MAX_ALPN bytes.
tape
import os from "os";
import time from "time";
import x509 from "x509";
import ca_roots from "ca_roots";

var anchors: [ca_roots.COUNT]x509.Cert;
var store: x509.TrustStore = x509.trust_store(anchors[0..ca_roots.COUNT]);
ca_roots.load(&store) or { return 1; };
var entropy: [64]u8;
os.random_bytes(entropy[0..64]) or { return 1; };
var protocols: [1][]const u8;
protocols[0] = "http/1.1";
let cfg: tls.Config = tls.Config {
    server_name: "example.com";
    trust: &store;
    now_unix: time.unix_nanos() / 1000000000;
    entropy: entropy[0..64];
    alpn: protocols[0..1];
};

Starting

tape
pub fn Client.start(*self, cfg: *const Config) -> void or TlsError

Resets the client, checks the configuration and queues the ClientHello in c.engine.output(). A Client can be started again for the next connection.

BadServerName when server_name is neither a host name (letters, digits, - and ., labels of 1 to 63 bytes, at most 253 bytes; a trailing dot is dropped) nor an IP address. These are mistakes in the program and stop it (a trap): entropy not 64 bytes, an ALPN name empty or over 255 bytes, an ALPN list over MAX_ALPN, a pin that is not 32 bytes, and no trust with no pin.

tape
c.start(&cfg) or {
    io.println("cannot start: {err}");     // "server name is not a valid host name or IP address"
    return 1;
};

Moving bytes

tape
pub fn Engine.output(*const self) -> []const u8
pub fn Engine.advance_output(*self, n: i64)
pub fn Engine.input_space(*const self) -> i64
pub fn Engine.feed(*self, data: []const u8) -> i64 or TlsError
pub fn Engine.end_of_input(*self) -> void or TlsError

These, and everything below up to Pinning but phase and failed_in, are the engine’s: c.engine.feed(data) for a client, s.engine.feed(data) for a server.

output() is what to send next: a view into the engine, valid until the next call that changes it. Send some or all of it and say how much with advance_output(n).

feed takes what the transport delivered, as much as fits (input_space() bytes), processes every whole record and returns how many bytes it took. Records may arrive split anywhere, even a byte at a time. When the server’s application data is waiting to be read, feed stops taking records until you read it, and may take 0 bytes: read, then feed the rest.

When the transport reaches its end, call end_of_input. After the server’s close_notify that is fine; before it, it is Truncated: an attacker who cuts the connection must not make a truncated answer look complete.

Every error is fatal and comes with an alert for the server in output(): send it if you can, then close the transport. From then on feed returns the same error again.

tape
fn flush(e: *tls.Engine, t: *Transport) -> bool {      // a client's or a server's
    while (e.output().len > 0) {
        let n: i64 = t.send(e.output()) or { return false; };
        e.advance_output(n);
    }
    return true;
}

fn handshake(e: *tls.Engine, t: *Transport) -> void or tls.TlsError {
    var buf: [16384]u8;
    while (!e.is_connected()) {
        flush(e, t);
        let n: i64 = t.receive(buf[0..16384]);
        if (n == 0) { e.end_of_input() or return; }
        var off: i64 = 0;
        while (off < n) {
            let took: i64 = e.feed(buf[off..n]) or {
                flush(e, t);                        // the alert, best effort
                return err;
            };
            off = off + took;
        }
    }
    flush(e, t);                                    // the client Finished
}

handshake(&c.engine, &t) runs it for a client.

Reading and writing

tape
pub const MAX_PLAINTEXT: i64 = 16384;
pub const MAX_RECORD: i64 = 16645;

pub fn Engine.read(*self, dst: []u8) -> i64
pub fn Engine.pending(*const self) -> i64
pub fn Engine.write(*self, src: []const u8) -> i64 or TlsError
pub fn Engine.update_keys(*self, request_peer: bool) -> bool
pub fn Engine.close(*self)

read copies decrypted data into dst and returns the count, 0 when nothing is waiting (pending says how much is). It never fails; errors come from feed. When it empties a record, the client goes on with the records it already holds, so after feeding everything you can keep reading.

write encrypts up to MAX_PLAINTEXT bytes of src into one record queued in output() and returns how many it took; 0 when the output is full: send it first. Writing before the handshake completes, or after close, is a mistake in the program and traps (is_connected() says when you may write).

update_keys replaces the client’s send key now (TLS 1.3 KeyUpdate), and with request_peer asks the server to replace its own; false when the output is full. The client also does this on its own before an AES-GCM key has protected 2^24 records, and answers the server’s requests.

close sends close_notify. Writing after it traps, but reading goes on until the server’s own close_notify (peer_closed()), as TLS 1.3 closes each direction on its own.

tape
var sent: i64 = 0;
while (sent < body.len) {
    let n: i64 = c.engine.write(body[sent..body.len]) or { return; };
    if (n == 0) { flush(&c.engine, t); }    // output full: send, then go on
    sent = sent + n;
}
flush(&c.engine, t);

var answer: [4096]u8;
let got: i64 = c.engine.read(answer[0..4096]);

Inspecting

tape
pub fn Client.phase(*const self) -> State
pub fn Client.failed_in(*const self) -> ?State
pub fn Engine.is_connected(*const self) -> bool
pub fn Engine.peer_closed(*const self) -> bool
pub fn Engine.error(*const self) -> ?TlsError
pub fn Engine.cert_error(*const self) -> ?x509.X509Error
pub fn Engine.alert(*const self) -> ?Alert
pub fn Engine.suite(*const self) -> ?Suite
pub fn Engine.group(*const self) -> ?Group
pub fn Engine.retried(*const self) -> bool
pub fn Engine.alpn(*const self) -> ?[]const u8
pub fn Engine.leaf_sha256(*const self) -> ?[]const u8

phase and failed_in are the client’s own (c.phase()), as a server’s states differ; the rest are the engine’s (c.engine.alert()).

FunctionGives
phase()where the handshake is: State.WaitServerHello … Connected, or Failed
is_connected()the handshake is complete: you may write
peer_closed()the server sent close_notify: no more data will come
error()the error that failed the client, null while it works
failed_in()the state it was in when it failed
cert_error()with a certificate failure, x509’s precise reason
alert()the last alert the server sent: fatal, and code, an AlertCode (its desc() is the RFC name)
suite(), group()the negotiated cipher suite and key-exchange group
retried()the server asked for another key share (HelloRetryRequest)
alpn()the protocol the server chose, null when none
leaf_sha256()the SHA-256 of the server’s certificate, once it arrived
tape
c.engine.feed(data) or {
    io.println("TLS failed: {err} while {c.failed_in()!.desc()}");
    let why: ?x509.X509Error = c.engine.cert_error();
    if (why != null) { io.println("  certificate: {why!}"); }
    let a: ?tls.Alert = c.engine.alert();
    if (a != null) { io.println("  the server said: {a!.code}"); }    // "no_application_protocol"
    return;
};
io.println("{c.engine.suite()!.desc()} over {c.engine.group()!.desc()}");   // TLS_AES_128_GCM_SHA256 over x25519

Pinning a certificate

For a server you know, you can pin its certificate by the SHA-256 of its DER (what leaf_sha256() reports). With a trust store as well, the chain must hold and the certificate must be the pinned one. With trust: null, the pin is the whole check: no chain to a root, no name match and no validity dates, so it works without a clock and for a self-signed certificate. The server must still prove it holds the certificate’s key. Any other certificate fails with LeafPinMismatch.

tape
let pinned: tls.Config = tls.Config {
    server_name: "debug.local";
    trust: null;                               // the pin alone
    now_unix: 0;                               // not used without a store
    entropy: entropy[0..64];
    pin_leaf_sha256: known_hash[0..32];
};

A pin is only as good as the way the hash reached your program: ship it with the program, and ship a new one when the server’s certificate changes.

The server

tape
pub struct ServerConfig {
    entropy: []const u8;             // ENTROPY_LEN (64) random bytes
    alpn: []const []const u8 = [];   // our protocols, preferred first
    alpn_required: bool = false;     // no protocol in common: refuse
}

pub fn Server.start(*self, cfg: *const ServerConfig) -> void or TlsError
pub fn Server.phase(*const self) -> ServerState
pub fn Server.failed_in(*const self) -> ?ServerState
pub fn Server.server_name(*const self) -> ?[]const u8
pub fn Server.use_certificate(*self, chain: []const []const u8, key: *const x509.PrivateKey) -> void or TlsError
pub fn Server.refuse(*self)

A Server is the other end of the same protocol, the same size as a Client, driven the same way through its engine: output, advance_output, input_space, feed, end_of_input, read, pending, write, update_keys, close and wipe, and for inspecting is_connected, peer_closed, error, alert (the client’s), suite, group, retried and alpn (the protocol chosen). phase and failed_in are its own and give a ServerState. It sends no session tickets, asks for no client certificate and takes no 0-RTT data.

start resets the server to wait for a ClientHello. When one has been fed and checked, the server pauses: phase() is ServerState.NeedCertificate, nothing has been sent yet, and server_name() is the name the client asked for (null when it sent none, as for an IP address). Choose a certificate chain by that name and call use_certificate, or refuse when you have none for it (the client gets unrecognized_name and the server fails with CertificateRefused). A server with one certificate answers at once, in the same loop step; net.Certificates does the choosing for several.

use_certificate takes the chain as DER certificates, the leaf first, and the leaf’s private key as x509.parse_private_key reads it (once, when the program loads its key). Nothing is copied but what is sent, so the views need to live only through the call. It queues the server’s whole answer and goes on with what was already fed. KeyMismatch when the key is not the leaf’s; HandshakeFailure when the client cannot verify the key’s signature (a P-256 key signs with ECDSA P-256/SHA-256, a P-384 key with ECDSA P-384/SHA-384, an RSA key with RSA-PSS/SHA-256); either fails the server, with its alert queued.

tape
fn serve(s: *tls.Server, t: *Transport, chain: []const []const u8, key: *const x509.PrivateKey,
         entropy: []const u8) -> void or tls.TlsError {
    let cfg: tls.ServerConfig = tls.ServerConfig { entropy: entropy; };
    s.start(&cfg) or return;
    let e: *tls.Engine = &s.engine;
    var buf: [16384]u8;
    while (!e.is_connected()) {
        flush(e, t);                                // the client's flush, as it is
        let n: i64 = t.receive(buf[0..16384]);
        if (n == 0) { e.end_of_input() or return; }
        var off: i64 = 0;
        while (off < n) {
            let took: i64 = e.feed(buf[off..n]) or { flush(e, t); return err; };
            off = off + took;
            if (s.phase() == tls.ServerState.NeedCertificate) {
                // one certificate for every name; refuse() when there is none
                s.use_certificate(chain, key) or { flush(e, t); return err; };
            }
        }
    }
    flush(e, t);
}

What the server chooses:

  • The suite: the first the client offers of TLS_AES_128_GCM_SHA256, TLS_CHACHA20_POLY1305_SHA256, TLS_AES_256_GCM_SHA384, with ChaCha20 first on a processor without AES instructions.
  • The key exchange: the client’s X25519 share, else its P-256 share, else one HelloRetryRequest asking for X25519 (retried()); a second ClientHello still without it is IllegalParameter.
  • ALPN: the first of alpn that the client offers. None in common means no protocol (alpn() is null), or with alpn_required the no_application_protocol alert and NoApplicationProtocol. A client that offers no ALPN at all is served without.
  • A client offering only TLS 1.2 or older gets protocol_version (ProtocolVersion). A client in middlebox compatibility mode (a session id, as most browsers and OpenSSL send) gets its id back and a change_cipher_spec record, and its own change_cipher_spec records are dropped.

Types

tape
pub enum Suite : u16 { Aes128GcmSha256 = 0x1301; Aes256GcmSha384 = 0x1302; ChaCha20Poly1305Sha256 = 0x1303; }
pub enum Group : u16 { Secp256r1 = 0x0017; X25519 = 0x001d; }
pub enum State : u8 {
    Start; WaitServerHello; WaitRetriedServerHello; WaitEncryptedExtensions;
    WaitCertificate; WaitCertificateVerify; WaitFinished; Connected; Failed;
}
pub enum ServerState : u8 {
    Start; WaitClientHello; NeedCertificate; WaitRetriedClientHello;
    WaitClientFinished; Connected; Failed;
}
pub enum AlertCode : u8 {
    CloseNotify = 0: "close_notify";
    UnexpectedMessage = 10: "unexpected_message";
    // ... every TLS 1.3 alert (RFC 8446 §6), by its RFC name ...
    NoApplicationProtocol = 120: "no_application_protocol";
}
pub struct Alert { fatal: bool; code: AlertCode; }
pub struct Engine { ... }                      // @opaque
pub struct Client { engine: Engine; }
pub struct Server { engine: Engine; }

Each desc() is the IANA name ("TLS_CHACHA20_POLY1305_SHA256", "secp256r1", "unrecognized_name") or the state in words ("waiting for Certificate"). A peer may send an alert code TLS 1.3 does not define: code keeps it (code as u8 is the number) and its desc() is empty. tls.AlertCode.desc(n) names a raw byte, such as the second byte of an alert record.

An Engine (and so a Client or a Server) is a plain struct of about 53 KiB with no pointers into itself: put one in a global, on the heap or in a large stack frame, and use one per connection.

Errors

tape
pub enum TlsError : u8 {
    BadRecord = 1: "malformed TLS record";
    RecordOverflow = 2: "TLS record too large";
    BadRecordMac = 3: "TLS record failed authentication";
    UnexpectedMessage = 4: "unexpected TLS message";
    DecodeError = 5: "malformed TLS handshake message";
    HandshakeTooLarge = 6: "TLS handshake message exceeds the engine's buffer";
    ProtocolVersion = 7: "server does not support TLS 1.3";
    HandshakeFailure = 8: "no common cipher suite, group or signature algorithm";
    IllegalParameter = 9: "server chose a value the client did not offer";
    UnsupportedExtension = 10: "server sent an extension the client did not offer";
    MissingExtension = 11: "server omitted a required extension";
    BadCertificate = 12: "server certificate is malformed, unsupported or not allowed for this use";
    CertificateExpired = 13: "server certificate has expired or is not yet valid";
    UnknownCa = 14: "server certificate does not chain to a trusted root";
    NameMismatch = 15: "server certificate does not match the server name";
    BadCertificateVerify = 16: "server's CertificateVerify signature does not verify";
    BadFinished = 17: "server's Finished does not verify";
    PeerAlert = 18: "server sent a fatal alert";
    Truncated = 19: "connection closed without close_notify";
    BadServerName = 20: "server name is not a valid host name or IP address";
    LeafPinMismatch = 21: "server certificate is not the pinned one";
    NoApplicationProtocol = 22: "no ALPN protocol in common with the client";
    KeyMismatch = 23: "private key does not match the certificate";
    CertificateRefused = 24: "no certificate for the server name the client asked for";
}

The certificate errors (BadCertificate, CertificateExpired, UnknownCa, NameMismatch) keep x509’s reason in cert_error(). PeerAlert means the peer ended the connection: alert() says why (a no_application_protocol, 120, when the server speaks none of your ALPN protocols). A server uses the same errors where they apply (a client’s Finished that does not verify is BadFinished, its fatal alert PeerAlert); the last three are the server’s own.

Secrets

The key schedule and the record protection are @constant_time; the engine wipes its key-exchange key and handshake secrets as soon as it no longer needs them.

tape
pub fn Engine.wipe(*self)

wipe zeroes every secret left in the client or server (the traffic keys, the buffers with their plaintext) when you are done with a connection; it can then only be started again. What the inspecting functions report stays. A server’s private key is yours: the engine reads it during use_certificate and keeps nothing of it.

Notes

  • The constant-time guarantee is for native code; the VM computes the same results without it.
  • Tested with the RFC 8448 traces (the engine’s records match the RFC’s byte for byte), in-memory handshakes against a test server with every suite, chain, signature, HelloRetryRequest and ALPN case and every misbehaviour it can be made to show, fed whole and a byte at a time, and against OpenSSL’s s_server. The server engine is tested against the client engine in memory (split into pieces of every size from 1 to 11 bytes) and against OpenSSL’s s_client.

Last modified: