Verifying TLS certificates
When a program dials a TLS server, the server sends a chain of certificates:
its own first, then the ones that signed it. nish/crypto/pki decides whether
that chain is one to trust: that it leads to a root the program trusts, that
every certificate on the way is valid now and allowed to do what it does, and
that the server's certificate names the host the program meant to reach.
Without that check, TLS encrypts the connection to whoever answered. The
module is part of the standard library and is imported
like any other (export and import).
Verifying a chain
pkiTrustStore(roots) builds the store of roots to trust, once.
pkiVerifyServer(chain, hostname, nowMs, store) checks one chain: chain is
each certificate's DER as the server sent it, its own certificate first and
the rest in any order; hostname is the name the program dialled; nowMs is
the time to check validity at, in milliseconds since the epoch. It answers a
PkiResult: code is PKI_OK or the reason it was refused, and path is
the chain it accepted, the server's certificate first and the root last.
import { PkiRoots, pkiLoadSystemRoots } from "nish/crypto/pki-roots";
import { PKI_OK, PkiResult, PkiTrustStore, pkiReason, pkiTrustStore, pkiVerifyServer } from "nish/crypto/pki";
const check = (chain: u8[][], host: string, store: PkiTrustStore): boolean => {
const r: PkiResult = pkiVerifyServer(chain, host, toI64(Date.now()), store);
if (r.code !== PKI_OK) {
console.log(`refused ${host}: ${pkiReason(r.code)}`);
return false;
}
console.log(`trusted ${host} through ${r.path.length} certificates`);
return true;
};
export const main = (): i32 => {
const roots: PkiRoots = pkiLoadSystemRoots();
const store: PkiTrustStore = pkiTrustStore(roots.roots);
// A chain from nowhere is refused: it has no certificates.
const chain: u8[][] = [];
return check(chain, "example.com", store) ? 0 : 1;
};
A refusal means the connection must not be used. There is no setting that skips a check, and none should be added in a program: a chain that fails is exactly what an attacker in the middle sends.
Loading roots
nish/crypto/pki-roots reads the roots where OpenSSL and Go look:
the file SSL_CERT_FILE names and every directory in SSL_CERT_DIR, when
either is set, and otherwise the system's bundle. It is native only. A
wasm32 program has no files to read, so it brings its own roots: parse each
PEM with pemToDer and x509ParseCertificate from nish/crypto/x509 and
pass the certificates to pkiTrustStore. nish/crypto/pki itself compiles
for wasm32.
On macOS the roots come from /etc/ssl/cert.pem. A root added only to the
Keychain, or a trust setting changed there, is not seen; export it to a PEM
file and name that file in SSL_CERT_FILE.
Distrusting a key
Revocation is not checked (see below), so a CA that is still in the system's
bundle stays trusted until the bundle drops it. To stop trusting one
sooner, or a key you know is compromised, name its key:
pkiDistrustSpki(store, hash) adds the SHA-256 of a certificate's
subjectPublicKeyInfo, 32 bytes, and from then on pkiVerifyServer refuses,
with PKI_ERR_DISTRUSTED, any chain whose path holds a certificate with that
key: the server's own, an intermediate or a root. The key is matched, not the
name, so every certificate issued for it is refused, cross-signs and reissues
too. It is the hash HTTP public key pinning used; for a PEM certificate,
openssl x509 -in cert.pem -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256 prints it in hex. A store distrusts nothing
until you call it, and a hash that is not 32 bytes is not added: the call
answers false.
import { PKI_ERR_DISTRUSTED, PkiTrustStore, pkiDistrustSpki, pkiTrustStore } from "nish/crypto/pki";
import { sha256 } from "nish/crypto/sha256";
import { X509Certificate } from "nish/crypto/x509";
// Trust `roots`, but no chain through the key of `retired`.
const storeWithout = (roots: X509Certificate[], retired: X509Certificate): PkiTrustStore => {
const store: PkiTrustStore = pkiTrustStore(roots);
pkiDistrustSpki(store, sha256(retired.spki));
return store;
};
export const main = (): i32 => {
const store: PkiTrustStore = storeWithout([], new X509Certificate());
return PKI_ERR_DISTRUSTED === 17 && store.roots.length === 0 ? 0 : 1;
};
X509Certificate.spki is the subjectPublicKeyInfo's DER, whole. A TLS
client distrusts a key with tlsClientDistrustSpki(trust, hash)
(TLS client), and fetch with its distrustSpkiSha256
option (HTTP client).
Reason codes
Each refusal has a code of its own, and pkiReason(code) gives its sentence.
When several paths were tried, the reason is the one from the attempt that got
nearest a root.
| Code | Meaning |
|---|---|
PKI_OK |
the chain is trusted and names the host |
PKI_ERR_MALFORMED |
the chain is empty, a certificate does not parse, or one breaks the profile a server's chain keeps: a missing key identifier, an extension marked critical when it must not be or not when it must, a zero or overlong serial number, a DNS name with an underscore |
PKI_ERR_EXPIRED |
a certificate's validity ended before nowMs |
PKI_ERR_NOT_YET_VALID |
a certificate's validity starts after nowMs |
PKI_ERR_UNTRUSTED |
no path leads to a root of the store |
PKI_ERR_BAD_SIGNATURE |
a signature does not verify under its issuer's key, or an RSA key is under 1024 or over 8192 bits |
PKI_ERR_NOT_CA |
an issuer is not a CA certificate, or the server's is one |
PKI_ERR_PATH_LENGTH |
an issuer's limit on the CAs below it is exceeded |
PKI_ERR_KEY_USAGE |
a key is used for something its key usage does not allow |
PKI_ERR_EXT_KEY_USAGE |
a certificate is not for TLS servers |
PKI_ERR_UNKNOWN_CRITICAL |
a certificate has a critical extension this module does not know |
PKI_ERR_NAME_CONSTRAINTS |
a name is outside what an issuer may certify, an issuer excludes a directory name, or it constrains a name form this module does not check |
PKI_ERR_HOSTNAME |
the server's certificate does not name the host |
PKI_ERR_WEAK_KEY |
a key is too small (an RSA key of 1024 to 2047 bits), or an RSA modulus is not a whole number of bytes |
PKI_ERR_UNSUPPORTED_ALGORITHM |
a signature or key algorithm is not supported, SHA-1 among them |
PKI_ERR_CHAIN_TOO_LONG |
the chain or a path is longer than its bound |
PKI_ERR_BUDGET |
checking would take more work than its bound allows |
PKI_ERR_DISTRUSTED |
a certificate on the path has a key the store distrusts (pkiDistrustSpki) |
The bounds are constants: PKI_MAX_CHAIN_CERTS (128) certificates and
PKI_MAX_CHAIN_BYTES (1 MiB) in a chain, PKI_MAX_PATH (8) certificates in a
path, PKI_MAX_SIGNATURES (64) signatures and PKI_MAX_NAME_CHECKS name
comparisons in one call, and PKI_MAX_NAMES and PKI_MAX_SUBTREES in one
certificate.
Hostnames
The host is matched against the server certificate's DNS names and IP
addresses, never its common name. Letters match without case, and a wildcard
is only a whole leftmost label: *.example.com names www.example.com but
not example.com or a.b.example.com. An IP address, 192.0.2.1 or ::1,
matches only an IP address in the certificate. A DNS host must be ASCII:
pass an internationalized name in its A-label form (xn--…), or the result
is PKI_ERR_HOSTNAME. pkiMatchHostname(leaf, host)
is that match alone, and pkiVerifySignature(cert, issuer) is whether one
certificate's signature verifies under another's key.
What is not checked
- Revocation. Neither CRLs nor OCSP are read, so a certificate revoked before it expires is still accepted, unless you distrust its key yourself.
- Whether name constraints are critical. A name constraints extension binds whether it is marked critical or not. Every other extension marked against the profile refuses the chain: a critical authority key identifier or, on the server's certificate, extended key usage; basic constraints not critical on an issuer; a policy constraints not critical; or a subject alternative name whose marking does not follow whether the subject is empty.
- Certificate policies are not processed.
- The common name is never read as a hostname.
A root is checked as an issuer is: an expired root, one without basicConstraints, one with an extended key usage and one whose name constraints the server's names break are refused, and a root's path length constraint binds the CAs below it. A TLS-inspection proxy's root that carries an extended key usage therefore anchors nothing. The server's certificate is checked against the CA/Browser Forum's profile: it may not sign certificates, carry name constraints or allow any extended key usage, and its key must be RSA of 2048 bits or more, P-256, P-384 or Ed25519.
A certificate that breaks the profile is refused as PKI_ERR_MALFORMED: one
below the root without an authorityKeyIdentifier, a root whose
authorityKeyIdentifier has no key identifier or names its issuer and serial,
a malformed authorityInfoAccess, a serial number of zero or of
more than 20 octets, or a DNS name with an underscore, which some private CAs
still issue. The checks follow the x509-limbo test suite, and the cases where
they differ are listed in the security record.
The security record, crypto-pki.md, lists what was checked and what is open.
On the server side
A server built on nish/net/tls-tcp's TlsTcpServer presents its own chain
and key; nothing here checks the client's, since client certificates are not
offered. Its key exchange is x25519 whenever the client lists x25519, and
secp256r1 (P-256) only for a client that lists P-256 alone. A client that
sends no share of the chosen group is asked once, with a HelloRetryRequest,
for one; and a P-256 share that is not an uncompressed point on the
curve is refused with the illegal_parameter alert.
A client may ask for smaller records with the record_size_limit extension
(RFC 8449), as a client short of memory does. The server keeps every
encrypted record it sends within that limit and tells the client its own,
16,385 bytes. Nothing in the program changes: write cuts what it is given
into as many records as the limit needs. Each record costs 22 bytes on the
wire, so at the smallest limit, 64, about a third of what is sent is
overhead. A limit below 64 is refused with the illegal_parameter alert,
and a malformed one with decode_error.
The pool has a fixed number of slots, so a client that connects and then says
nothing would hold one for good. Call expire(monotonicNanos()) from the
program's poll loop (monotonicNanos is in nish:process): it closes every
slot that has neither read nor written for idleTimeout milliseconds and
answers how many it closed. idleTimeout is 60,000 (a minute) by default;
set it on the server to change it, or to 0 to turn it off and keep the
timeout in the program. Call expire after the program has handled every
event one pollWait returned, not between them, so an event for a slot it
closes is not taken for the next connection in that slot. It bounds idleness,
not the length of a handshake: a client that sends a byte within every
timeout keeps its slot. The record,
tls.md, lists this as TLS-4.

