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.