nish/net/tls/client

The client side of a TLS 1.3 handshake (RFC 8446), from its ClientHello to its Finished, carrier-agnostic and sans-IO: the mirror of nish/net/tls's TlsServer.

import {
  TLS_CLIENT_STATE_CONNECTED,
  TLS_CLIENT_STATE_FAILED,
  TLS_CLIENT_STATE_START,
  TLS_CLIENT_STATE_WAIT_AUTH,
  TLS_CLIENT_STATE_WAIT_CERTIFICATE,
  TLS_CLIENT_STATE_WAIT_CERTIFICATE_VERIFY,
  TLS_CLIENT_STATE_WAIT_ENCRYPTED_EXTENSIONS,
  TLS_CLIENT_STATE_WAIT_FINISHED,
  TLS_CLIENT_STATE_WAIT_SERVER_HELLO,
  TlsClient,
  TlsClientConfig,
  tlsClientIsIpLiteral,
} from "nish/net/tls/client";
import { TlsClient, TlsClientConfig } from "nish/net/tls/client";

const client = new TlsClient(new TlsClientConfig("example.com", ["h2"]), random, x25519Key, p256Key);
client.start();
// send client.takeOutput(TLS_LEVEL_INITIAL); hand the server's bytes to
// client.receive(level, bytes, 0, n); install secrets as they are known;
// at TLS_CLIENT_STATE_WAIT_AUTH check peerCertificates() and the
// signature, then client.authenticate(ok) (or client.reject(alert)).

It lives in a module of its own, beside nish/net/tls and not re-exported by it, since Nish has no re-exports; the levels and TLS_SECRET_* indices it shares with the server are nish/net/tls's.

Carrier-agnostic

As the server does, the client reads and writes handshake messages tagged with their level — the ClientHello and the ServerHello at Initial, the rest of the server's flight and the client's Finished at Handshake — and its secrets are readable as they become known. nish/net/tls/record-client puts it on a byte stream.

Sans-IO

The client random and both private keys, x25519's and P-256's, are constructor arguments. Nothing here reads a socket, a clock or the random device.

Authentication is the caller's

Once the server's CertificateVerify is read, the client stops at TLS_CLIENT_STATE_WAIT_AUTH without looking at the chain or the signature: peerCertificates, verifyScheme, verifyContent and verifySignature hand them out, and only authenticate(true) goes on to the server's Finished and writes the client's. A caller that drives this class directly must make that call itself, after checking the chain against its trust anchors and the signature over verifyContent() under the leaf's key: nothing here does either, and nothing proves the peer is who serverName says until then (docs/security/tls.md, "The client").

What is offered

TLS 1.3 only, with a 32-byte legacy_session_id for middlebox compatibility (§D.4). The suites, groups and first key share are the configuration's: by default the three suites this tree negotiates and the group x25519; secp256r1 may be configured too, for the first share or for a HelloRetryRequest to pick. signature_algorithms lists ECDSA P-256 and P-384 and RSA-PSS; server_name is sent unless the name is an IP literal (RFC 6066 §3); ALPN is the configuration's. One HelloRetryRequest is answered (§4.1.4); resumption, 0-RTT and client certificates are not here, and a NewSessionTicket is read and dropped.

Refusals are alerts. receive, authenticate and reject answer 0 or a TLS alert description (TLS_ALERT_* in nish/net/tls/codec); after one the client is in TLS_CLIENT_STATE_FAILED, every secret it held is wiped, and it answers the same alert to every call. Nothing the peer sends can make it panic.

Secrets

Both private keys are copied into Secret fields and the caller's arrays zeroed; the one the server did not pick is wiped when it picks, and both once the exchange is done. The ECDHE secret is a Secret wiped on every path; the handshake, traffic and exporter secrets are the fields of two TlsSecretPools. fail and wipe zero them all.

The state is a class and a switch, with no closures. Written from RFC 8446, RFC 7301 and RFC 6066, not ported from another implementation.

Functions

tlsClientIsIpLiteral

Whether name is an IP literal, which RFC 6066 §3 keeps out of server_name: dotted decimal (digits and dots only), or anything with a colon, which no DNS name has.

const tlsClientIsIpLiteral: (name: string) => boolean
namestringrequired

A host name as the caller gave it, such as TlsClientConfig.serverName.

returnsboolean

True when name is non-empty and all digits and dots, or holds a colon anywhere; such a name is not sent as server_name.

Classes

TlsClient

The client side of one TLS 1.3 handshake, sans-IO: it takes the server's handshake messages through receive, writes its own for takeOutput, and derives each secret into secrets() as it becomes known. It never judges the server's certificate itself: at TLS_CLIENT_STATE_WAIT_AUTH it waits for the caller's authenticate or reject. One instance serves one connection; once it fails or is wiped it stays failed.

class TlsClient
Member
new TlsClient(config: TlsClientConfig, clientRandom: u8[], x25519Private: u8[], p256Private: u8[]) A client for one connection under config, with the 32-byte client random and the 32-byte x25519 and P-256 private keys drawn for it; both keys are copied in and the caller's arrays zeroed. A random or key of another length, or a configuration it cannot offer, leaves the client failed with internal_error before it writes anything.
alert: i32 The alert the client failed with, or 0.
alpnChosen: string The ALPN protocol the server chose, one of the configuration's, or empty.
retried: boolean Whether a HelloRetryRequest was read, so a second is fatal.
scheme: i32 The CertificateVerify scheme.
sentServerName: boolean Whether server_name was sent, so that only then may the server acknowledge it.
sessionId: u8[] The legacy_session_id sent, which the ServerHello must echo.
shareGroup: i32 The group of the key share the last ClientHello carried.
state: i32 Where the handshake is: one of the TLS_CLIENT_STATE_* values, TLS_CLIENT_STATE_CONNECTED once it has finished and TLS_CLIENT_STATE_FAILED once alert is set.
suite: i32 The negotiated cipher suite, or 0 before the ServerHello (or HelloRetryRequest) is read.
alpn(): string The ALPN protocol the server chose, or empty when it chose none.
authenticate(ok: boolean): i32 The caller's verdict on the server's chain and signature, at TLS_CLIENT_STATE_WAIT_AUTH: true goes on to the server's Finished, reading what was held meanwhile; false is reject(bad_certificate). Answers 0 or the alert; in any other state the client fails with internal_error.
peerCertificates(): u8[][] The server's DER certificates, leaf first; empty before its Certificate is read.
receive(level: i32, data: u8[], off: i32, len: i32): i32 Takes the handshake bytes data[off .. off + len) the server sent at level, a whole message, part of one or several, and reads every message they complete. Answers 0, or the alert the client fails with.

A level other than the one the state expects is unexpected_message, as is a byte left over once a message ends the server's flight at its level (a ServerHello, a HelloRetryRequest or a Finished): RFC 8446 §5.1 forbids a message to straddle a key change. A window outside data is internal_error. At TLS_CLIENT_STATE_WAIT_AUTH the bytes are held until authenticate. Once connected, the Application level takes NewSessionTickets, which are checked and dropped; anything else there is unexpected_message, KeyUpdate being the record layer's.
reject(alert: i32): i32 Refuses the server at TLS_CLIENT_STATE_WAIT_AUTH with alert, the caller's reason (bad_certificate, certificate_expired, unknown_ca, decrypt_error…): the client fails with it and answers it. An alert outside 1 to 255 is taken as bad_certificate. In any other state the client fails with internal_error.
secrets(): TlsSecretPool The pool of the negotiated hash: SHA-384's for a SHA-384 suite, SHA-256's otherwise.
start(): i32 Writes the first ClientHello at the Initial level. Answers 0, or the alert the client failed with; a second call is internal_error.
takeOutput(level: i32): u8[] The handshake bytes written at level since the last call, in a fresh array, and forgets them.
verifyContent(): u8[] What the CertificateVerify signature is over (§4.4.3): 64 spaces, the server's context string, a zero byte and the transcript hash.
verifyScheme(): i32 The CertificateVerify scheme (TLS_SIGNATURE_*); 0 before it is read.
verifySignature(): u8[] The CertificateVerify signature as sent: DER for ECDSA, raw for RSA-PSS.
wipe(): void Wipes every secret the client holds, both private keys and both pools, and fails it: a wiped client has nothing left to go on with. fail calls it, and the carriers when a connection ends; wiped without a failure, it answers internal_error from then on.

TlsClientConfig

What a client is configured with, the same for every connection. The constructor fills in the defaults; a caller may narrow suites or groups or change shareGroup before handing it to a TlsClient, which checks it.

class TlsClientConfig
Member
new TlsClientConfig(serverName: string, alpn: string[]) A configuration for serverName offering alpn, with every suite this tree negotiates and an x25519 share. Nothing is checked here: TlsClient's constructor checks the whole configuration.
alpn: string[] The ALPN protocols offered, most preferred first; empty sends no ALPN. Each is 1 to 255 bytes.
groups: i32[] The groups offered in supported_groups: a non-empty subset of x25519 and secp256r1.
serverName: string The host the client means to reach: sent as server_name unless it is an IP literal, and the name the caller authenticates.
shareGroup: i32 The group of the one key share the first ClientHello carries; one of groups.
suites: i32[] The cipher suites offered, most preferred first: a non-empty subset of the three this tree negotiates.

Constants

7

TLS_CLIENT_STATE_CONNECTED: i32

Both Finished are done and the application secrets known.

8

TLS_CLIENT_STATE_FAILED: i32

The handshake failed or was wiped: every secret is zeroed, and alert says why. No state follows it.

0

TLS_CLIENT_STATE_START: i32

Built; start has not written the ClientHello yet.

5

TLS_CLIENT_STATE_WAIT_AUTH: i32

The server's chain and signature are read and wait for the caller's verdict: authenticate or reject. Bytes that arrive meanwhile are held, not read.

3

TLS_CLIENT_STATE_WAIT_CERTIFICATE: i32

EncryptedExtensions is read; the server's Certificate comes next, at the Handshake level. A CertificateRequest here is unexpected_message: this client does not authenticate itself.

4

TLS_CLIENT_STATE_WAIT_CERTIFICATE_VERIFY: i32

The server's chain is read; its CertificateVerify comes next, at the Handshake level.

2

TLS_CLIENT_STATE_WAIT_ENCRYPTED_EXTENSIONS: i32

The handshake secrets are known; EncryptedExtensions comes next, at the Handshake level.

6

TLS_CLIENT_STATE_WAIT_FINISHED: i32

The caller accepted the server; its Finished comes next.

1

TLS_CLIENT_STATE_WAIT_SERVER_HELLO: i32

The ClientHello is out; a ServerHello or HelloRetryRequest comes next, at the Initial level.