nish/net/tls/verify

The TLS client's one authentication seam: whether the server a TlsRecordClient reached is the one its serverName says, decided at TLS_RECORD_AUTH and handed to the connection as its verdict.

import {
  TLS_ALERT_CERTIFICATE_EXPIRED,
  TLS_ALERT_UNKNOWN_CA,
  TLS_VERIFY_MIN_RSA_BITS,
  TlsClientTrust,
  tlsClientAuthenticate,
  tlsClientChain,
  tlsClientDistrustSpki,
  tlsClientSystemTrust,
  tlsClientTrust,
  tlsClientVerdict,
  tlsVerifyCertificateVerify,
} from "nish/net/tls/verify";
const trust: TlsClientTrust = tlsClientSystemTrust();
// when conn.interest() says TLS_RECORD_AUTH:
const alert: i32 = tlsClientAuthenticate(conn, trust, toI64(Date.now()));
Two checks, both always made

The CertificateVerify first: its scheme must be one this client offered and fit the leaf's key — ECDSA P-256 with SHA-256 on a P-256 key, ECDSA P-384 with SHA-384 on a P-384 key, RSA-PSS (rsae, salt as long as the hash) on an RSA key of at least 2048 bits — and the signature must verify over TlsClient.verifyContent() under that key (RFC 8446 §4.4.3). Then the chain, from the leaf the server sent to a root in trust, for the name the caller dialled.

A server with no certificate or a leaf that does not parse is bad_certificate, as is a leaf whose key is of any other kind (Ed25519, a short RSA modulus); a signature that does not verify, or a scheme that does not fit the key, is decrypt_error. The signature goes first so a forged CertificateVerify reads as what it is whatever the chain would have said.

The chain is `nish/crypto/pki`'s

pkiVerifyServer builds a path from the leaf to a root of trust's store and checks every certificate on it — signatures, validity at the instant given, basicConstraints, keyUsage, serverAuth, name constraints — and that the leaf's subjectAltName names the host dialled. Its refusal becomes the alert: certificate_expired for a certificate outside its validity, unknown_ca when no path reaches a root of the store, and bad_certificate for every other reason, a key distrusted with tlsClientDistrustSpki among them. There is no switch that skips the step and none is to be added: a client that is to talk to a server it cannot authenticate is given a store holding its issuing root, never a way around the check (docs/security/tls.md, "The client carrier and verify").

The verdict is the record client's to send: tlsClientAuthenticate calls authenticate(true) or reject(alert) on it, so the refusal goes out as a fatal alert under the handshake keys. Written from RFC 8446 §4.2.3 and §4.4.3, not ported from another implementation.

Functions

tlsClientAuthenticate

Authenticates client's server, while its interest says TLS_RECORD_AUTH: tlsClientVerdict, then client.authenticate(true) on 0 or client.reject(alert) otherwise, which seals the alert. Answers 0 or the alert the connection failed with.

const tlsClientAuthenticate: (
  client: TlsRecordClient,
  trust: TlsClientTrust,
  nowMs: i64,
) => i32
clientTlsRecordClientrequired

The record-layer client, whose interest says TLS_RECORD_AUTH.

trustTlsClientTrustrequired

The roots the server's chain must lead to.

nowMsi64required

The instant to judge validity at, in milliseconds since 1970-01-01 UTC.

returnsi32

0 when the server was accepted and the handshake went on, else the alert the connection failed with: the verdict's, or one client.authenticate(true) reports.

tlsClientChain

The chain step: 0 when chain (DER, leaf first) leads to a root in trust and names serverName at nowMs, else the alert — certificate_expired, unknown_ca or bad_certificate.

const tlsClientChain: (
  chain: u8[][],
  serverName: string,
  nowMs: i64,
  trust: TlsClientTrust,
) => i32
chainu8[][]required

Each certificate's DER as the server sent it, the leaf first.

serverNamestringrequired

The name or address dialled, ASCII (an internationalised name in its A-label form).

nowMsi64required

The instant to judge validity at, in milliseconds since 1970-01-01 UTC.

trustTlsClientTrustrequired

The roots the chain must lead to.

returnsi32

0 when the chain is accepted, else TLS_ALERT_CERTIFICATE_EXPIRED (also for a certificate not yet valid), TLS_ALERT_UNKNOWN_CA, or TLS_ALERT_BAD_CERTIFICATE for every other refusal.

tlsClientDistrustSpki

Distrusts a key in trust: every connection made with it from now on refuses, with bad_certificate, a server whose path holds a certificate (leaf, intermediate or root) whose subjectPublicKeyInfo DER hashes to spkiSha256 under SHA-256 (pkiDistrustSpki). It is how a program stops trusting a CA its roots still hold, or a key known to be compromised, before the system bundle drops it. A trust distrusts nothing until this is called.

const tlsClientDistrustSpki: (
  trust: TlsClientTrust,
  spkiSha256: u8[],
) => boolean
trustTlsClientTrustrequired

The trust to change; every connection that shares it sees the change.

spkiSha256u8[]required

The SHA-256 of the subjectPublicKeyInfo DER, 32 bytes.

returnsboolean

Whether the hash was added: false, and nothing added, unless it is 32 bytes long.

tlsClientSystemTrust

The trust of the system's roots (pkiLoadSystemRoots): what a client trusts unless it is given a store. It reads the roots from disk each time it is called, so a program makes it once and shares it.

const tlsClientSystemTrust: () => TlsClientTrust
returnsTlsClientTrust

A trust over the roots SSL_CERT_FILE and SSL_CERT_DIR name, or else the system bundle's.

tlsClientTrust

The trust of roots, as nish/crypto/pki-roots read them.

const tlsClientTrust: (roots: PkiRoots) => TlsClientTrust
rootsPkiRootsrequired

The roots a loader such as pkiLoadSystemRoots read; only their parsed certificates are kept.

returnsTlsClientTrust

A trust to hand to tlsClientAuthenticate, tlsClientVerdict or tlsClientChain.

tlsClientVerdict

The verdict on tls's server at TLS_CLIENT_STATE_WAIT_AUTH: 0 when the CertificateVerify verifies under the leaf's key and the chain leads from that leaf to a root in trust for the configured server name at nowMs (milliseconds since 1970-01-01 UTC), else the alert to refuse with.

const tlsClientVerdict: (
  tls: TlsClient,
  trust: TlsClientTrust,
  nowMs: i64,
) => i32
tlsTlsClientrequired

The client, stopped at TLS_CLIENT_STATE_WAIT_AUTH; it is only read, not advanced.

trustTlsClientTrustrequired

The roots the server's chain must lead to.

nowMsi64required

The instant to judge validity at, in milliseconds since 1970-01-01 UTC.

returnsi32

0 when the server is authenticated; TLS_ALERT_BAD_CERTIFICATE for an empty chain, a leaf that does not parse or whose key is unusable; TLS_ALERT_DECRYPT_ERROR when the signature does not verify; else tlsClientChain's answer.

tlsVerifyCertificateVerify

Whether signature, as a CertificateVerify carries it under scheme, verifies over content under leaf's key. false for a scheme that does not fit the key's kind and for every scheme this client does not offer.

const tlsVerifyCertificateVerify: (
  leaf: X509Certificate,
  scheme: i32,
  content: u8[],
  signature: u8[],
) => boolean
leafX509Certificaterequired

The server's leaf certificate, whose public key the signature must verify under.

schemei32required

The TLS_SIGNATURE_* code point the CertificateVerify names.

contentu8[]required

The bytes the server signed, as RFC 8446 §4.4.3 builds them from the transcript hash.

signatureu8[]required

The signature as sent: DER for ECDSA, the raw modulus-sized value for RSA-PSS.

returnsboolean

True only when the signature verifies under leaf's key with scheme.

Classes

TlsClientTrust

The roots a client trusts, indexed once and shared by every connection made with them.

class TlsClientTrust
Member
new TlsClientTrust(roots: X509Certificate[]) Indexes roots once, so every connection made with this trust looks its issuers up in the same store rather than scanning the list again.

Limits

2,048

TLS_VERIFY_MIN_RSA_BITS: i32

The smallest RSA modulus a CertificateVerify is checked under, in bits: the Web PKI's floor.

Constants

45

TLS_ALERT_CERTIFICATE_EXPIRED: i32

certificate_expired (RFC 8446 §6.2): the leaf or a certificate above it is outside its validity.

48

TLS_ALERT_UNKNOWN_CA: i32

unknown_ca (RFC 8446 §6.2): no path from the chain reaches a root the client trusts.