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)).
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.
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.
TlsClientConfig
What a client is configured with, the same for every connection.
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
namestringrequiredA 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.

