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.