Skip to content

cert.md

Latest commit

 

History

History
100 lines (74 loc) · 4.79 KB

cert.md

File metadata and controls

100 lines (74 loc) · 4.79 KB
Raw

Certificate Authority

PMG inspects package downloads through a transparent HTTPS proxy. To read encrypted traffic it acts as a man in the middle (MITM), signing a short lived certificate for each registry host with its own Certificate Authority (CA). Package managers must trust that CA for the interception to work.

Default behavior: ephemeral CA via environment variables

By default PMG generates a CA for each run and injects it into the package manager process through environment variables such as NODE_EXTRA_CA_CERTS, SSL_CERT_FILE, REQUESTS_CA_BUNDLE, and PIP_CERT. The CA lives only for the duration of that run and is discarded afterwards.

This requires no setup and covers the common cases: npm, pip, and Go on Linux.

When you need a persistent CA trusted by the OS

Environment variable injection does not reach tools that consult only the operating system trust store. The most important case is Go on macOS and Windows. Go's TLS stack on those platforms ignores SSL_CERT_FILE and validates against the platform verifier (Security.framework on macOS, CryptoAPI on Windows). On Linux, Go honors SSL_CERT_FILE, so the default behavior already covers it.

For those cases you can install a single persistent PMG CA into the OS trust store. This also avoids regenerating a CA on every run.

# User scope (no sudo). macOS login keychain / Windows CurrentUser\Root.
pmg setup cert install

# System scope (all users). Run as your normal user, NOT with sudo.
# PMG prompts for sudo only for the trust store write (macOS / Linux).
# Windows: run from an elevated prompt.
pmg setup cert install --system

# Inspect presence, trust scope, expiry, and drift.
pmg setup cert status

# Rotate (regenerate and trust again).
pmg setup cert install --force

# Remove from the trust store. --purge also deletes the keypair on disk.
pmg setup cert uninstall [--system] [--purge]

Trust scopes

pmg setup cert install installs at user scope by default, which needs no elevation. Pass --system to install for all users. Always run the command as your normal user, not under sudo. PMG generates a keypair owned by you and elevates only the trust store write, prompting for sudo on macOS and Linux. On Windows, run it from an elevated prompt. Running the whole command under sudo is refused, because the keypair would be persisted in root's config directory where the unprivileged proxy never looks.

Platform User scope (default) System scope (--system)
macOS login keychain System keychain (sudo)
Windows CurrentUser\Root LocalMachine\Root (admin)
Linux not available, see below /usr/local/share/ca-certificates or /etc/pki/ca-trust (sudo)

Linux has no user trust store. Running pmg setup cert install without --system on Linux persists the keypair and relies on SSL_CERT_FILE injection, which already covers Go on Linux. Use --system to trust the CA for all users.

Storage and security

The CA keypair is stored under PMG's config directory as ca-cert.pem (0644) and ca-key.pem (0600). The private key never leaves disk. Only the public certificate is installed into the OS trust store, since the trust store cannot hold or return a private key.

The keypair always belongs to you. The unprivileged proxy must read the private key it signs with, so the command runs as your normal user and writes to your config directory. --system only widens where the public certificate is trusted, not where the key lives.

A persistent CA that the OS trusts is sensitive. Anyone who can read ca-key.pem can intercept your TLS traffic for tools that trust the CA. PMG mitigates this with restrictive file permissions and a clean uninstall path. Reading the key requires local filesystem access, at which point the host is already compromised.

Rotation and expiry

The root CA is valid for 10 years. Leaf certificates, one per host, stay short lived (one day) and are never installed anywhere. A long lived root is standard practice because rotating an installed, trusted root is disruptive. The root is protected by guarding its key rather than by frequent rotation.

Rotation is manual. Run pmg setup cert install --force to regenerate and trust the CA again. Both pmg setup cert status and pmg setup doctor warn when the root is within 30 days of expiry.

Drift and diagnostics

pmg setup cert status reports whether the keypair is present, which scope trusts it, the fingerprint, and the expiry. It also flags drift, for example a certificate on disk without its private key, or a CA that is on disk but not trusted in the OS store.

pmg setup doctor includes a CA health check. On macOS and Windows a CA on disk that is not trusted is reported as a failure, with pmg setup cert install as the fix. On Linux it is a warning, since SSL_CERT_FILE injection already covers Go.