nish/net/tls/record-client
A TLS 1.3 client over a byte stream: the record layer of nish/net/tls/record wrapped around nish/net/tls/client's TlsClient, sans-IO. Bytes the server sent go in, bytes to send come out, and once the handshake is done application data flows both ways. The mirror of nish/net/tls/record-server.
import {
TLS_RECORD_AUTH,
TlsRecordClient,
} from "nish/net/tls/record-client";
const conn = new TlsRecordClient(new TlsClient(config, random, x25519Key, p256Key));
// send conn.output[conn.outputStart .. conn.outputEnd), then conn.consume(sent)
conn.receive(bytes, 0, n); // what the socket read
if ((conn.interest() & TLS_RECORD_AUTH) !== 0) {
// check conn.tls.peerCertificates() and the CertificateVerify
conn.authenticate(verified);
}
const got: i32 = conn.read(buf, 0, buf.length); // application data
What it adds to `TlsClient`
Records around the handshake messages: the
ClientHello in the clear, then the client's Finished under the handshake
keys, and every key installed at the record boundary RFC 8446 §5.1 puts it
on. The middlebox-compatibility change_cipher_spec of §D.4, which a client
that sends a session id (this one always does) owes: one, in the clear,
before its second ClientHello after a HelloRetryRequest, or else before its
first protected record; the server's is dropped from its first handshake
record until its Finished.
Alerts (§6) both ways, as the server has them: close_notify ends the
server's stream, user_canceled is passed over, any other alert ends the
connection, and a refusal of this module's or of TlsClient's is sent as a
fatal alert under whatever keys the client writes with. KeyUpdate (§4.6.3)
both ways, with the server's limits: TLS_RECORD_IDLE_LIMIT records in a row
that carry nothing, and TLS_RECORD_MAX_KEY_UPDATES KeyUpdates. A
NewSessionTicket is handed to TlsClient, which checks and drops it; any
other post-handshake message is unexpected_message (no client certificate
is offered, so no CertificateRequest). A stream that ends without
close_notify is truncation.
Authentication is the caller's
At TlsClient's WAIT_AUTH the
records after the server's CertificateVerify stay in the reader and
interest says TLS_RECORD_AUTH: nothing more is read until the caller
has checked the chain and the signature and called authenticate(true) —
or authenticate(false) / reject(alert), which fail the connection with
the alert sent. Nothing here proves who the server is.
Buffers
One connection, one object: output, plain and scratch
are allocated with it, and wipe zeroes the two that hold plaintext. The
handshake's messages are sealed straight out of TlsClient's own buffers.
Secrets
As in TlsRecordServer: TlsClient holds the handshake's
secrets, this object the two application traffic secrets, one readonly
field per direction and hash length, with readHash and writeHash saying
which of each pair is live. A secret is copied out of TlsClient as it is
installed and the client's copy zeroed; the handshake secrets are zeroed
once the Finished messages no longer need them; a KeyUpdate overwrites
the live field in place. A failure of any kind wipes everything both
objects hold once the last alert is sealed; the client's close_notify,
once sealed, wipes the write direction, and the server's the read
direction; wipe wipes the rest (TLS-1, TLS-3 and "The client" 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
TlsRecordClient
One TLS 1.3 client connection over a stream. Make one per connection
around a fresh TlsClient, which it starts, and drive it with receive,
consume, read, write and authenticate as interest says.
The fields are readable: state, alert (the alert this client sent, or
0), peerAlert (the error alert the server sent, or -1), peerClosed
(the server's close_notify arrived), tls (the handshake: suite, ALPN,
the server's certificates, exporter secret), and the two protections with
their sequence numbers. padding is how many zero bytes each protected
record the client writes carries after its content type (§5.4).
class TlsRecordClient
| Member | |
|---|---|
new TlsRecordClient(tls: TlsClient) |
Wraps tls, which should be fresh, and starts it: the ClientHello is sealed into output at once. A tls that has already failed, or whose ClientHello cannot be written, fails this connection with its alert queued in the clear. |
alert: i32 |
The alert this client sent, or 0. |
keyUpdates: i32 |
How many KeyUpdates from the server this client has taken, up to TLS_RECORD_MAX_KEY_UPDATES. |
output: u8[] |
Bytes to send are output[outputStart .. outputEnd). |
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 client writes carries after its content type (§5.4). |
peerAlert: i32 |
The error alert the server sent, or -1 when it sent none. |
peerClosed: boolean |
True once the server's close_notify has arrived. |
readProtection: TlsRecordProtection |
Opens the server's records; its sequence number counts the records read at the current keys. |
state: i32 |
Where the connection stands: one of the TLS_RECORD_STATE_* constants. |
tls: TlsClient |
The handshake underneath: read it for the suite, ALPN, the server's certificates and the exporter secret. |
writeProtection: TlsRecordProtection |
Seals the client's records; its sequence number counts the records written at the current keys. |
abort(): void |
The socket failed under the connection: it ends with nothing more sent, and every key it holds wiped. |
authenticate(ok: boolean): i32 |
The caller's verdict on the server's certificate chain and CertificateVerify, while interest says TLS_RECORD_AUTH (TlsClient.authenticate): true reads on to the server's Finished and seals the client's; false fails the connection with bad_certificate sent. Answers 0, or a non-zero alert once the connection has failed (failure) — a verdict given before one is due answers internal_error. |
close(): void |
Closes the client's side (§6.1): a close_notify, after which write answers TLS_RECORD_PIPE. Application data already written stays ahead of the alert; the write keys are wiped once it is sealed. Closed before the handshake is done — before the client's Finished is sealed — the client reads nothing more, and the read keys and everything TlsClient holds are wiped at once. 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 server's TCP stream ended: the orderly end after its close_notify, truncation before it. |
failure(): i32 |
Why a failed connection failed, never 0: the alert the client sent, else the server's error alert, else internal_error for a failure with no alert of its own (truncation, abort, close_notify mid-handshake). |
interest(): i32 |
What the connection wants next, as TLS_RECORD_* bits: read the socket, write it, read, the caller's verdict on the server (TLS_RECORD_AUTH), or nothing more ever (TLS_RECORD_DONE). |
keyUpdate(requestPeer: boolean): i32 |
Sends a KeyUpdate now, asking the server 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 client has closed or the connection failed, or TLS_RECORD_RESET when the next keys do not install. |
read(buf: u8[], off: i32, len: i32): i32 |
Application data from the server, into buf[off .. off + len): the count; 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; TLS_RECORD_INVALID for a window outside buf. |
receive(data: u8[], off: i32, len: i32): i32 |
Takes bytes of the server's stream, data[off .. off + len), and handles every record they complete. Answers how many it took, fewer than len only when its buffers are full, or TLS_RECORD_INVALID for a window outside data. Once the connection has failed, the server has sent close_notify, or the client closed before the handshake was done, bytes are taken and dropped (§6.1). |
reject(alert: i32): i32 |
Refuses the server with the caller's alert (TlsClient.reject), sent; answers the alert. |
space(): i32 |
How many bytes receive would take now: what the socket should read at most. |
wipe(): void |
Wipes everything this connection holds: both traffic secrets at both hash lengths, both directions' keys, the plaintext buffers and everything TlsClient holds, so read has nothing more to give. Call it when the connection is done with. |
write(data: u8[], off: i32, len: i32): i32 |
Application data for the server, data[off .. off + len): seals as much as fits, in records of at most 2^14 bytes, and answers how much that was. A KeyUpdate goes first when the key has protected recordLimit records, or the server asked for one. TLS_RECORD_AGAIN while the handshake is under way or nothing fits, TLS_RECORD_PIPE once the client has closed or the connection failed, TLS_RECORD_INVALID for a window outside data. |
Constants
64
TLS_RECORD_AUTH: i32
An interest bit beside nish/net/tls/record-server's TLS_RECORD_*:
the server's chain and CertificateVerify wait for the caller's verdict,
authenticate or reject.

