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
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.
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.
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.
pkiRootsDirEntry
Whether a directory entry is one a trust directory holds: *.pem, *.crt, or the hash form xxxxxxxx.N.
pkiSystemBundles
The system bundles, in the order they are tried; the first one that reads as a file is used.
PkiRoots
The trust store one load found.
The order (docs/security/crypto-pki.md, "Where the roots come from"):
-
When
SSL_CERT_FILEorSSL_CERT_DIRis 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. -
Otherwise the first file of
pkiSystemBundles()that exists, and the directory/etc/ssl/certsbeside 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 | nullrequiredA file to read first, or null for none.
dirsstring[]requiredThe directories to read every trust entry of.
bundlesstring[]requiredThe candidate bundle files; only the first that reads is used.
returnsPkiRootsA 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 | nullrequiredThe 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[]requiredThe directories read when neither variable is set; ignored when either is.
bundlesstring[]requiredThe bundle files tried when neither variable is set; ignored when either is.
returnsPkiRootsA 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
namestringrequiredThe 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.

