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
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.
TlsRecordServer
One TLS 1.3 server connection over a stream.
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.

