Trusting the Crusader CA

01Why you trust a CA

Crusader is a man-in-the-middle proxy. To read and rewrite HTTPS, it terminates TLS, then re-encrypts to the client with a leaf certificate it mints on the fly — one per host, signed by a root CA that Crusader generates per machine. Your browser (or app) will reject those leaf certs with a TLS error until it trusts the Crusader root. Trust the root once and every site Crusader proxies validates cleanly.

The root is created the first time Crusader needs it: subject CN=Crusader Root CA, O=Crusader Security, OU=HTTPS Interception, a 10-year RSA-2048 root, with per-host SHA-256 leaves. It never leaves your machine, and the private key stays in a password-protected, 0600 file.

02Where the CA lives

Everything sits under ~/.crusader/ca/ (relocate the whole workspace with the CRUSADER_HOME environment variable). Three files, and only one of them is the one you import:

03The one-click path: Install CA

The first-run wizard — titled "Trust the Crusader certificate" — offers Install certificate and Open test browser. You'll also find Install CA as step 03 of the intercept setup overlay ("Make interception predictable."). Click it and Crusader imports the public root into the correct store for your OS, with whatever native trust prompt that store requires.

Under the hood, Install CA runs exactly the manual commands documented below — the same ones you'd type yourself. The per-OS sections show what it does, in case you're scripting a fresh VM, a CI runner, or a locked-down host where you'd rather run the step by hand. From the CLI, the equivalent is:

# one-click trust, headless — same store, same prompts
crusader proxy install-ca

# just print the path to the public cert
crusader proxy cert-path

After trust succeeds the wizard confirms "You're ready to intercept HTTPS." If you'd rather not trust the root system-wide at all, jump to the test browser.

04Manual — macOS

macOS trust goes into your login keychain, so it needs no admin — just your login password at the prompt. Install CA uses the PEM copy and marks it as a trusted root:

# login keychain — prompts for your login password, no sudo
security add-trusted-cert -r trustRoot \
  -k ~/Library/Keychains/login.keychain-db \
  ~/.crusader/ca/crusader-root.pem

That trusts the root for every app that reads the system/login trust roots, Safari and Chrome included. Firefox keeps its own store (see the Linux section's NSS notes — the same applies on macOS Firefox).

05Manual — Windows

Windows trust goes into the current user's Root store (CurrentUser\Root) — no admin required. Windows shows its own security-warning dialog the first time you add a root; accept it. This uses the DER .cer file:

# CurrentUser\Root — no elevation, shows the Windows trust prompt
certutil -user -f -addstore Root %USERPROFILE%\.crusader\ca\crusader-root.cer

That covers everything on Windows that uses the OS trust store — Chrome, Edge, and the WebView-based clients. As elsewhere, Firefox carries its own store and isn't covered by this command.

06Manual — Linux (system + browser)

Linux is two stores, not one. The system trust store is shared OS-wide; browsers (Chrome, Chromium, Firefox) keep their own NSS database and ignore the system store. You usually need both.

System trust (needs admin)

Crusader elevates via pkexec/sudo, drops the cert in the distro's anchor directory, then runs the distro's update command. The path and command differ per family:

# Debian / Ubuntu
sudo cp ~/.crusader/ca/crusader-root.pem \
  /usr/local/share/ca-certificates/crusader-root.crt
sudo update-ca-certificates

# Fedora / RHEL
sudo cp ~/.crusader/ca/crusader-root.pem \
  /etc/pki/ca-trust/source/anchors/crusader-root.pem
sudo update-ca-trust extract

# Arch
sudo cp ~/.crusader/ca/crusader-root.pem \
  /etc/ca-certificates/trust-source/anchors/crusader-root.pem
sudo trust extract-compat

Browser trust (NSS — needs a browser restart)

Chrome, Chromium, and Firefox read an NSS database under your home directory, not the system store. Add the root there with certutil (from libnss3-tools / nss-tools — Crusader auto-installs it if missing):

# Chrome / Chromium NSS store (~/.pki/nssdb)
certutil -d sql:$HOME/.pki/nssdb -A -t "C,," \
  -n "Crusader Root CA" -i ~/.crusader/ca/crusader-root.pem

Firefox keeps a per-profile cert9.db; Crusader also handles the snap/flatpak NSS locations. After adding the cert you must restart the browser for it to pick up the new root.

07Per-OS cheat sheet

The store and command Install CA uses on each platform, at a glance:

08The zero-install path: test browser

Sometimes you don't want to touch the system trust store at all — a shared box, a quick test, or a site that refuses a user-installed CA on principle. HSTS-preloaded sites (banks, Google, att.com) ship a hard pin in the browser binary and will reject even a correctly trusted user root. That's not a Crusader bug; it's the point of HSTS preload.

For those, use Open test browser (the primary button in the CA wizard). It launches an installed Chromium-family browser in an isolated, throwaway profile under your temp directory, routes it through Crusader, and pins the Crusader root by its SHA-256 SPKI rather than installing anything:

# what Open test browser does, conceptually
chrome \
  --user-data-dir=<temp profile> \
  --proxy-server=127.0.0.1:<port> \
  --ignore-certificate-errors-spki-list=<crusader root SPKI>

Because the trust is scoped to exactly the Crusader root (not "ignore all cert errors") and applies only to this disposable profile, it's safe to use and leaves your real browser and system stores untouched. It auto-starts the proxy if it's off, and it works on HSTS-preloaded sites where store-based trust can't. This is the easiest path overall.

Next

Want a guide that isn't here yet? Email hello@crusaderproxy.com.