nish/crypto/pki-roots

The root certificates a program should trust, read from where OpenSSL and Go look for them: the files SSL_CERT_FILE and SSL_CERT_DIR name, or else the system's bundle.

import {
  PKI_ROOTS_MAX_FILES,
  PKI_ROOTS_MAX_FILE_BYTES,
  PKI_ROOTS_MAX_ROOTS,
  PKI_SYSTEM_DIR,
  PkiRoots,
  pkiLoadRoots,
  pkiLoadRootsFor,
  pkiLoadSystemRoots,
  pkiRootsDirEntry,
  pkiSystemBundles,
} from "nish/crypto/pki-roots";
import { PkiRoots, pkiLoadSystemRoots } from "nish/crypto/pki-roots";

const store: PkiRoots = pkiLoadSystemRoots();
// store.roots: the parsed roots, no two with the same DER
// store.sources: the files they were read from, in order
// store.skipped: the PEM blocks and files that were not a root

The order (docs/security/crypto-pki.md, "Where the roots come from"):

  1. When SSL_CERT_FILE or SSL_CERT_DIR is set and not empty, exactly those: the file, and every directory of the :-separated list. There is no fallback, so naming a file that is missing trusts nothing.
  2. Otherwise the first file of pkiSystemBundles() that exists, and the directory /etc/ssl/certs beside it.

Only a path that leads to a regular file is read. A directory gives every entry named *.pem, *.crt or OpenSSL's hash form xxxxxxxx.N, not its subdirectories. A file is split into PEM blocks here, not by pemToDer, which refuses a whole text for one bad block: a CERTIFICATE block x509ParseCertificate accepts is a root, and every other block — a malformed one, an unterminated one, a TRUSTED CERTIFICATE — is counted in skipped and passed over. Finding nothing is an empty roots, never an exit: what to do with no roots is the caller's decision.

Whoever sets the environment or writes these files decides what is trusted. That is the contract, as it is OpenSSL's, and it is not defended against; what is bounded is the work a hostile file can cause (PKI-R1 to PKI-R3).

Native only

It asks lstatOwnerModeSync what each path is before it reads it, which a wasm32 build has no file system to answer, so a program that imports this module does not compile for wasm32 (PKI-R4). nish/crypto/x509 imports nothing from here.

Private helpers share the importing program's flat symbol namespace (docs/wp26-stdlib.md §3e), which is why each one carries the module's name.

Functions

pkiLoadRoots

The roots of an explicit lookup: file when it is not null, then the first of bundles that reads as a file, then every directory of dirs, in that order. A path that cannot be read contributes nothing; a duplicate DER is kept once, where it was first read.

const pkiLoadRoots: (
  file: string | null,
  dirs: string[],
  bundles: string[],
) => PkiRoots
filestring | nullrequired

A file to read first, or null for none.

dirsstring[]required

The directories to read every trust entry of.

bundlesstring[]required

The candidate bundle files; only the first that reads is used.

returnsPkiRoots

A new PkiRoots with what was found, empty when nothing was.

pkiLoadRootsFor

pkiLoadSystemRoots with the two variables' values given, and the defaults it falls back to: what it does with the environment, without reading it, so the order can be tested against fixture trees rather than the host's /etc. certFile and certDir are SSL_CERT_FILE and SSL_CERT_DIR, null when unset; an empty value counts as unset.

const pkiLoadRootsFor: (
  certFile: string | null,
  certDir: string | null,
  dirs: string[],
  bundles: string[],
) => PkiRoots
certFilestring | nullrequired

The value of SSL_CERT_FILE, or null when unset.

certDirstring | nullrequired

The value of SSL_CERT_DIR, a :-separated list, or null when unset.

dirsstring[]required

The directories read when neither variable is set; ignored when either is.

bundlesstring[]required

The bundle files tried when neither variable is set; ignored when either is.

returnsPkiRoots

A new PkiRoots, as pkiLoadRoots gives it.

pkiLoadSystemRoots

The roots this program should trust: those SSL_CERT_FILE and SSL_CERT_DIR name when either is set and not empty, and otherwise the first of pkiSystemBundles() that exists and /etc/ssl/certs.

const pkiLoadSystemRoots: () => PkiRoots
returnsPkiRoots

A new PkiRoots, read afresh on every call; empty when nothing was found.

pkiRootsDirEntry

Whether a directory entry is one a trust directory holds: *.pem, *.crt, or the hash form xxxxxxxx.N.

const pkiRootsDirEntry: (name: string) => boolean
namestringrequired

The entry's name, without its directory.

returnsboolean

true for a name ending .pem or .crt with something before it, or eight lowercase hex digits, a dot and one or more decimal digits.

pkiSystemBundles

The system bundles, in the order they are tried; the first one that reads as a file is used. A function, not a constant, because a module constant is a number, a boolean or a string. The paths and their order are those of Go's crypto/x509/root_linux.go, cited as facts, not copied code: Debian, Ubuntu, Arch and Gentoo; Fedora and RHEL; openSUSE; OpenELEC; CentOS and RHEL 7; Alpine, macOS and the BSDs.

const pkiSystemBundles: () => string[]
returnsstring[]

The bundle paths, in a fresh array each call.

Classes

PkiRoots

The trust store one load found.

class PkiRoots
Member
new PkiRoots() An empty load: no roots, no sources, nothing skipped.
roots: X509Certificate[] The parsed roots, in the order they were read, no two with the same DER.
skipped: i32 The PEM blocks that were not a root, and the files too large or past the cap to read.
sources: string[] Every file that was read, in order, whether or not it held a root.

Limits

4,096

PKI_ROOTS_MAX_FILES: i32

The most files one load reads; an entry past it counts as one skip.

16,777,216

PKI_ROOTS_MAX_FILE_BYTES: i32

The largest file read as roots: 16 MiB, some eighty times a full Mozilla bundle. A bigger one counts as one skip.

4,096

PKI_ROOTS_MAX_ROOTS: i32

The most roots one load keeps; a certificate past it counts as one skip.

Constants

"/etc/ssl/certs"

PKI_SYSTEM_DIR: string

The directory read beside the system bundle.