nish/net/tls/record-server

A TLS 1.3 server over a byte stream: the record layer of nish/net/tls/record wrapped around nish/net/tls's TlsServer, sans-IO. Bytes the client sent go in, bytes to send come out, and once the handshake is done application data flows both ways.

import {
  TLS_RECORD_AGAIN,
  TLS_RECORD_DATA,
  TLS_RECORD_DONE,
  TLS_RECORD_IDLE_LIMIT,
  TLS_RECORD_INVALID,
  TLS_RECORD_MAX_KEY_UPDATES,
  TLS_RECORD_PIPE,
  TLS_RECORD_RESET,
  TLS_RECORD_SIGN,
  TLS_RECORD_STATE_CLOSED,
  TLS_RECORD_STATE_FAILED,
  TLS_RECORD_STATE_HANDSHAKE,
  TLS_RECORD_STATE_OPEN,
  TLS_RECORD_TICKET,
  TLS_RECORD_WANT_READ,
  TLS_RECORD_WANT_WRITE,
  TlsRecordPools,
  TlsRecordServer,
} from "nish/net/tls/record-server";
const conn = new TlsRecordServer(new TlsServer(config, random, key));
conn.receive(bytes, 0, n);                 // what the socket read
if ((conn.interest() & TLS_RECORD_SIGN) !== 0) {
  conn.sign(tlsSignEcdsaP256(leaf, conn.signatureInput()));
}
// send conn.output[conn.outputStart .. conn.outputEnd), then conn.consume(sent)
const got: i32 = conn.read(buf, 0, buf.length);   // application data
What it adds to `TlsServer`

Records around the handshake messages: ServerHello (or HelloRetryRequest) in the clear, the rest of the server's flight — EncryptedExtensions through Finished — in as few records as fit under the handshake keys once it is signed, which is one record for RFC 8448 §3's trace, and every key installed at the record boundary RFC 8446 §5.1 puts it on.

The middlebox-compatibility change_cipher_spec of §D.4: the server sends one right after its first handshake message when the client sent a session id, and drops the client's from its first ClientHello until its Finished. Alerts (§6) both ways: close_notify ends the client's stream, user_canceled is passed over, any other alert ends the connection, and a refusal of this module's or of TlsServer's is sent as a fatal alert under whatever keys the server writes with.

KeyUpdate (§4.6.3) both ways: the client's moves the read keys on and, when it asks, the server answers with its own; keyUpdate sends one, and the writer sends one by itself before a key has protected TLS_KEY_UPDATE_RECORDS records. More than TLS_RECORD_IDLE_LIMIT records in a row that carry nothing for the caller — KeyUpdates among them, which each cost two key derivations — are refused. A stream that ends without close_notify is truncation, but only once the records still waiting for the caller have been read.

Borrowed buffers

The record being read, the record being opened, the bytes to send and the application data waiting for the caller each live in an array borrowed from a TlsRecordPools when the connection first needs it, kept while the connection lasts, and given back zeroed with BufferPool.giveSecret when it ends (start, wipe, release), so a slot with no connection holds none of them, a connection that has finished its handshake allocates nothing that outlives a record, and a slot can be handed the next connection with start.

Each give-back zeroes the whole buffer, so it happens once a connection rather than once a record. The handshake's messages are sealed straight out of TlsServer's own buffers, and the application secrets are copied into this slot's fields, so a slot that hands its TlsServer the next connection with restart runs every handshake after the first without moving the arena, whichever suite it negotiates; a KeyUpdate's key install leaves nothing either (TLS-3 in docs/security/tls.md). When the caller leaves application data unread for long enough to fill its buffer, records stay in the reader and interest stops asking for reads, which is how the peer is made to wait.

Secrets

Each traffic secret is a Secret<u8[]> (nish:secret): TlsServer holds the handshake's in its TlsSecretPools, and this slot holds the two application traffic secrets in four readonly fields, one per direction and hash length, with readHash and writeHash saying which of each pair is live (0 when neither is).

A secret is copied out of TlsServer as it is installed and the server's copy is zeroed, as are the handshake secret once the flight is signed and the ephemeral key once the ServerHello is written, or the handshake fails; a KeyUpdate overwrites the live field in place with the next secret.

Every way the connection ends wipes what it holds: a failure of any kind (fail, the client's error alert, a truncated stream, abort) wipes both directions' keys, both secrets and everything TlsServer still holds once the last alert is sealed; the server's close_notify, once sealed, wipes the write direction, the client's the read direction, and close the resumption master secret; and wipe (which wipeKeys calls when the carrier closes the slot) and start wipe the rest. No secret leaves either object but through expose, so a secret cannot be logged or kept outside this module and nish/net/tls (TLS-1 in docs/security/tls.md).

Refusals are alerts, never panics. Written from RFC 8446 §4.6.3, §5, §6 and §D.4, not ported from another implementation.

Classes

TlsRecordPools

The four pools a connection's record buffers are borrowed from: output and plain for TlsRecordServer's fields of those names, scratch for the buffer it opens a record's content into, and reader for its record reader's buffer. A carrier with many slots makes one set with a ceiling of its slot count and points every slot at it with TlsRecordServer.borrowFrom, so a full server holds what preallocating every slot would have held and an idle one holds only what earlier connections left on the free lists. Each buffer goes back zeroed (BufferPool.giveSecret): it held plaintext, or handshake bytes.

class TlsRecordPools
Member
new TlsRecordPools(ceiling: i32) Four empty pools of ceiling buffers each; nothing is made until a slot needs it.
output: BufferPool Lends each slot its output buffer, where sealed records wait to be sent.
plain: BufferPool Lends each slot its plain buffer, where opened application data waits to be read.
reader: BufferPool Lends each slot its record reader's buffer.
scratch: BufferPool Lends each slot the buffer a record's content is opened into.
lent(): i32 How many buffers of the four pools are lent now: 0 once every connection has given its back.
made(): i32 How many buffers the four pools have made: their high-water mark together.

TlsRecordServer

One TLS 1.3 server connection over a stream. Allocate one per slot, hand it each connection's TlsServer with start, and drive it with receive, consume, read, write and sign as interest says.

The fields are readable: state, alert (the alert this server sent, or 0), peerAlert (the error alert the client sent, or -1), peerClosed (the client's close_notify arrived), tls (the handshake: suite, ALPN, server name, exporter secret), and the two protections with their sequence numbers. padding is how many zero bytes each protected record the server writes carries after its content type (§5.4), 0 unless the caller sets it.

A client that sent record_size_limit (RFC 8449) gets no protected record whose plaintext, content type and padding included, passes it: write and the handshake flight are cut into records of at most the limit less one less padding, and a padding that leaves no room fails the connection with internal_error as it does under 2^14. Records in the clear (ServerHello, HelloRetryRequest, the compatibility change_cipher_spec) are not limited.

class TlsRecordServer
Member
new TlsRecordServer(tls: TlsServer) Makes a slot for tls with a pool set of its own, one buffer of each kind, and starts the connection as start does. A carrier that shares its pools calls borrowFrom right after.
alert: i32 The alert this server sent, or 0.
closeDue: boolean The server has closed and its close_notify waits for room in output.
keyUpdates: i32 KeyUpdates taken from the client, against TLS_RECORD_MAX_KEY_UPDATES.
output: u8[] Bytes to send are output[outputStart .. outputEnd); empty until a record is sealed.
outputEnd: i32 One past the last byte still to send in output; outputStart when nothing is pending.
outputStart: i32 The index in output of the first byte still to send; consume(sent) moves it on.
padding: i32 How many zero bytes each protected record the server writes carries after its content type (§5.4); 0 unless the caller sets it.
peerAlert: i32 The error alert the client sent, or -1 when it sent none.
peerClosed: boolean True once the client's close_notify has arrived.
plain: u8[] Application data the caller has not read is plain[plainStart .. plainEnd); empty until a record brings some.
plainEnd: i32 One past the last unread byte in plain; plainStart when none is pending.
plainStart: i32 The index in plain of the first byte of application data the caller has not read.
readHash: i32 The hash length of the client's traffic secret in bytes (32 or 48), or 0 before it is known.
readProtection: TlsRecordProtection Opens the client's records; its sequence number counts the records read at the current keys.
readonly readTraffic256: Secret<u8[]> The client's and the server's current application traffic secrets, for KeyUpdate, each held at both hash lengths: readHash and writeHash say which of a pair holds the secret, and are 0 before it is known.
readonly readTraffic384: Secret<u8[]> The client's current application traffic secret when the hash is SHA-384, 48 bytes.
state: i32 Where the connection stands: one of the TLS_RECORD_STATE_* constants.
tls: TlsServer The handshake underneath: read it for the suite, ALPN, server name and exporter secret.
writeHash: i32 The hash length of the server's traffic secret in bytes (32 or 48), or 0 before it is known.
writeLevel: i32 The TLS_LEVEL_* the server's records are written at.
writeProtection: TlsRecordProtection Seals the server's records; its sequence number counts the records written at the current keys.
readonly writeTraffic256: Secret<u8[]> The server's current application traffic secret when the hash is SHA-256, 32 bytes.
readonly writeTraffic384: Secret<u8[]> The server's current application traffic secret when the hash is SHA-384, 48 bytes.
abort(): void The socket failed under the connection: it ends with nothing more sent, and every key it holds wiped.
borrowFrom(pools: TlsRecordPools): void Borrows the record buffers from pools from now on, a carrier's set its slots share. Whatever is held from the old pools is given back first, zeroed, and dropped with it, so call it on a slot with nothing in flight: the carrier does, right after the constructor.
close(): void Closes the server's side (§6.1): a close_notify, after which write answers TLS_RECORD_PIPE and nothing more is sent. What was still owed of the handshake is dropped; application data already written stays ahead of the alert, which waits for room in output when there is none. The resumption master secret is wiped, since nothing issues a ticket from it, and the write keys once the close_notify is sealed (sealClose). Nothing happens once the connection has failed or closed.
consume(n: i32): void Lets the first n bytes of output go, once the socket has taken them, and seals what was waiting for the room.
end(): void The client's TCP stream ended. After its close_notify that is the orderly end; before it, the stream was cut short — truncation, which an attacker on the path can cause — and the connection fails with nothing sent, since there is nobody left to read it.
fail(alert: i32): void Fails the connection with alert, sent as a fatal alert under whatever the server writes with now, in the clear before its first keys. What was still owed is dropped: the alert is the last thing the server sends, so once it is sealed every key the connection holds is wiped, the traffic keys and secrets as well as what TlsServer holds.
interest(): i32 What the connection wants next, as TLS_RECORD_* bits: read the socket (there is room, and the stream has not ended), write it (output holds bytes), read (application data, or the end of the client's stream), sign, handle a ticket, or nothing more ever (TLS_RECORD_DONE: failed or closed, and everything is sent).
issue(key: Secret<u8[]>, info: TlsTicketKeyInfo, now: i64): boolean While interest says TLS_RECORD_TICKET on an open connection: seals a ticket under key (TlsServer.issue) and queues its NewSessionTicket. Whether one was queued; either way the resumption master secret is wiped, and no second ticket is issued.
keyUpdate(requestPeer: boolean): i32 Sends a KeyUpdate now, asking the client to update too when requestPeer (§4.6.3). Answers 0, TLS_RECORD_AGAIN while the handshake is under way or output is full, TLS_RECORD_PIPE once the server has closed or the connection failed, or TLS_RECORD_RESET when the next keys do not install and the connection fails on it.
read(buf: u8[], off: i32, len: i32): i32 Application data from the client, into buf[off .. off + len): the count, as a socket read answers; 0 at the end of its stream (its close_notify) or for a len of 0; TLS_RECORD_AGAIN when nothing is waiting; TLS_RECORD_RESET once the connection has failed; and TLS_RECORD_INVALID for a window outside buf. Reading makes room, so records the buffer was full for are handled before it answers.
receive(data: u8[], off: i32, len: i32): i32 Takes bytes of the client's stream, data[off .. off + len), and handles every record they complete. Answers how many it took, which is fewer than len only when its buffers are full (read interest before reading the socket again), or TLS_RECORD_INVALID for a window outside data. Once the connection has failed, or the client has sent close_notify, bytes are taken and dropped (§6.1).
release(): void Gives back every record buffer this slot holds, zeroed, and drops what was in them: unsent output, unread application data and a partial record. The carrier calls it when it closes the slot, after the last flush and wipeKeys, so a free slot holds no buffer of the pools'.
resume(current: Secret<u8[]>, currentInfo: TlsTicketKeyInfo, previous: Secret<u8[]>, previousInfo: TlsTicketKeyInfo, strikes: TlsTicketStrikes, now: i64): i32 While interest says TLS_RECORD_TICKET in the handshake: reads the ClientHello's tickets under the keys the carrier lends (TlsServer.resume) and seals the flight that answers it, resumed or in full. Answers 0, or the alert the connection failed with — internal_error when no ticket waits.
sealRecord(type: i32, data: u8[], off: i32, len: i32): boolean Seals one record of type from data[off .. off + len) onto output under the write protection, padded when it is protected. False, writing nothing, when it does not fit; content and padding past writeCap() (the client's record_size_limit, or 2^14) and a refusal from seal itself fail the connection with internal_error.
sign(signature: u8[]): i32 Takes the signature over signatureInput() (DER for ECDSA, as tlsSignEcdsaP256 answers it) and seals the rest of the flight. Answers 0, or the alert the connection failed with — internal_error when no signature is due.
signatureInput(): u8[] | null What the CertificateVerify signs, while interest says TLS_RECORD_SIGN; null otherwise.
space(): i32 How many bytes receive would take now: what the socket should read at most.
start(tls: TlsServer): void Starts a new connection in this slot with tls, which should be fresh or just restarted (TlsServer.restart, which reuses its buffers): every buffer is emptied and given back, zeroed, and the keys of the last connection are wiped; nothing is allocated. A tls that has already failed — a configuration or randomness TlsServer refused — fails this connection at once, with its alert queued in the clear.
wipe(): void Wipes everything this slot holds, which is what wipeKeys does: both traffic secrets at both hash lengths, both directions' keys, and everything TlsServer holds. The record buffers that hold nothing still needed go back too; a failure's alert waiting in output stays until it is sent or release drops it.
wipeKeys(): void Wipes every key this connection holds: the two application traffic secrets it keeps for KeyUpdate, both directions' keys, and what is left in TlsServer (TlsServer.wipe). The carrier calls it when a slot is closed, so a free slot holds no key.
write(data: u8[], off: i32, len: i32): i32 Application data for the client, data[off .. off + len): seals as much as fits, in records of at most 2^14 bytes, and answers how much that was, as a socket write does. A KeyUpdate goes first when the key has protected recordLimit records, or the client asked for one. TLS_RECORD_AGAIN while the handshake is under way or nothing fits, TLS_RECORD_PIPE once the server has closed or the connection failed, and TLS_RECORD_INVALID for a window outside data.

Limits

16

TLS_RECORD_IDLE_LIMIT: i32

How many records in a row may carry nothing for the caller — a change_cipher_spec, empty application data, a user_canceled warning, a KeyUpdate or a piece of one — before the connection is refused with unexpected_message. Each costs the server work, a KeyUpdate two key derivations, and none moves the connection on. Sixteen is Go's maxUselessRecords; a record of application data, or of the handshake, starts the count again.

64

TLS_RECORD_MAX_KEY_UPDATES: i32

How many KeyUpdates one connection takes from its client before refusing the next with unexpected_message. Each costs one key install, two when the server answers, which leave nothing in the arena; the cap bounds the work a client can ask for, as TLS_RECORD_IDLE_LIMIT does in a row. A client that updates when RFC 8446 §5.5 asks, once per 2^24 records, reaches it after 2^30 records; §4.6.3 itself sets no limit, so one that updates on a clock of its own is cut off at the sixty-fifth, a trade-off TLS-3 records.

Constants

-11

TLS_RECORD_AGAIN: i32

What read, write and keyUpdate answer when they have to wait: Linux's EAGAIN, as nish:net spells it.

4

TLS_RECORD_DATA: i32

read has application data, or the end of the client's stream, to give.

16

TLS_RECORD_DONE: i32

Nothing more will happen: the connection failed or closed, and everything to send is sent.

-22

TLS_RECORD_INVALID: i32

What read and write answer for a window outside the caller's array: Linux's EINVAL.

-32

TLS_RECORD_PIPE: i32

What write answers once the server has closed: Linux's EPIPE, as nish:net spells it.

-104

TLS_RECORD_RESET: i32

What read and write answer once the connection has failed: Linux's ECONNRESET, as nish:net spells it.

8

TLS_RECORD_SIGN: i32

The server is waiting for its CertificateVerify signature: signatureInput, then sign.

2

TLS_RECORD_STATE_CLOSED: i32

The server's close_notify is written; it sends nothing more, and may still read.

3

TLS_RECORD_STATE_FAILED: i32

The connection ended on an alert, sent (alert) or received (peerAlert), or on a stream cut short.

0

TLS_RECORD_STATE_HANDSHAKE: i32

The handshake is under way.

1

TLS_RECORD_STATE_OPEN: i32

The client's Finished verified: application data flows both ways.

32

TLS_RECORD_TICKET: i32

A ticket is the carrier's to handle, with the keys and strike register it lends: during the handshake the ClientHello offers one, so resume reads it; once the connection is open the client may be issued one, so issue.

1

TLS_RECORD_WANT_READ: i32

There is room for more of the stream: read the socket.

2

TLS_RECORD_WANT_WRITE: i32

output holds bytes to send: write the socket.