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()));
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.
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.
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).
tlsClientSystemTrust
The trust of the system's roots (pkiLoadSystemRoots): what a client trusts unless it is given a store.
tlsClientTrust
The trust of roots, as nish/crypto/pki-roots read them.
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.
tlsVerifyCertificateVerify
Whether signature, as a CertificateVerify carries it under scheme, verifies over content under leaf's key.
TlsClientTrust
The roots a client trusts, indexed once and shared by every connection made with them.
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
clientTlsRecordClientrequiredThe record-layer client, whose interest says TLS_RECORD_AUTH.
trustTlsClientTrustrequiredThe roots the server's chain must lead to.
nowMsi64requiredThe 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[][]requiredEach certificate's DER as the server sent it, the leaf first.
serverNamestringrequiredThe name or address dialled, ASCII (an internationalised name in its A-label form).
nowMsi64requiredThe instant to judge validity at, in milliseconds since 1970-01-01 UTC.
trustTlsClientTrustrequiredThe 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
trustTlsClientTrustrequiredThe trust to change; every connection that shares it sees the change.
spkiSha256u8[]requiredThe SHA-256 of the subjectPublicKeyInfo DER, 32 bytes.
returnsbooleanWhether 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
returnsTlsClientTrustA 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
rootsPkiRootsrequiredThe roots a loader such as pkiLoadSystemRoots read; only their parsed certificates are kept.
returnsTlsClientTrustA 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
tlsTlsClientrequiredThe client, stopped at TLS_CLIENT_STATE_WAIT_AUTH; it is only read, not advanced.
trustTlsClientTrustrequiredThe roots the server's chain must lead to.
nowMsi64requiredThe 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
leafX509CertificaterequiredThe server's leaf certificate, whose public key the signature must verify under.
schemei32requiredThe TLS_SIGNATURE_* code point the CertificateVerify names.
contentu8[]requiredThe bytes the server signed, as RFC 8446 §4.4.3 builds them from the transcript hash.
signatureu8[]requiredThe signature as sent: DER for ECDSA, the raw modulus-sized value for RSA-PSS.
returnsbooleanTrue 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.

