From f77a9570e973dda7247c653754e62d5a9a895658 Mon Sep 17 00:00:00 2001 From: srdusr <99972264+srdusr@users.noreply.github.com> Date: Thu, 2 Apr 2026 20:55:00 +0200 Subject: Per-OS CA install instructions (mitmuxd -install-ca) Trusting the CA was previously "import ca.pem into whatever's making the requests" with no further help. -install-ca generates the CA if needed and prints copy-pasteable, OS-specific steps, then exits without starting the proxy. Deliberately instructions-only, never auto-executing anything: Linux trust-store tooling varies enough across distros (trust vs update-ca-trust vs update-ca-certificates) that guessing wrong and running the wrong command unattended is worse than asking, and installing a root CA is a system-wide trust change affecting every TLS connection on the machine, not just mitmux's own traffic - running the printed command themselves keeps the user in control of that. internal/ca/install.go: InstallInstructions(goos, caPath) dispatches by OS. Linux detects trust (p11-kit - Arch, also on Fedora) / update-ca-trust (RHEL/Fedora/CentOS) / update-ca-certificates (Debian/Ubuntu/Gentoo) via PATH lookup and prints whichever is actually present, plus separate certutil/NSS instructions for Firefox/Chrome's own certificate store (which doesn't always follow the system trust store on Linux). macOS (security add-trusted-cert) and Windows (certutil -addstore / Import-Certificate) are implemented from each platform's standard documented tooling but not verified live - no macOS/Windows machine was available to test against, unlike Linux. commandExists is a package var (not a direct exec.LookPath call) so tests can fake which tools are "present" and exercise every detection branch deterministically, independent of what's actually installed on whatever machine runs `go test`. Verified live: built mitmuxd, ran -install-ca against a throwaway CA dir on this (Arch Linux) machine - correctly detected `trust` and `certutil` on PATH and printed accurate commands, confirmed the CA files were actually generated, confirmed no proxy/daemon process was left running (exits immediately after printing), and confirmed running it a second time reuses the existing CA (identical file hash) rather than regenerating. go build/vet/gofmt/test/mod tidy all clean. --- internal/ca/install.go | 112 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 internal/ca/install.go (limited to 'internal/ca/install.go') diff --git a/internal/ca/install.go b/internal/ca/install.go new file mode 100644 index 0000000..bafcea4 --- /dev/null +++ b/internal/ca/install.go @@ -0,0 +1,112 @@ +package ca + +import ( + "fmt" + "os/exec" + "path/filepath" + "strings" +) + +// commandExists reports whether name is on PATH. Var, not a plain func +// call, so tests can substitute a fake lookup without touching the real +// PATH - trust-store tooling varies enough across distros that testing +// the actual detection logic (which command wins, in what order) matters +// more than testing against whatever happens to be installed on the +// machine running `go test`. +var commandExists = func(name string) bool { + _, err := exec.LookPath(name) + return err == nil +} + +// InstallInstructions returns copy-pasteable, OS-specific steps for +// trusting caPath as a root CA. It only ever prints commands - it never +// runs anything itself. Installing a root CA is a genuinely sensitive, +// system-wide trust change (and system trust-store tooling varies enough +// across distros that guessing wrong and auto-running the wrong command +// is worse than asking); the user running the printed command themselves +// keeps them in control of a change that affects every TLS connection on +// the machine, not just mitmux's own traffic. +func InstallInstructions(goos, caPath string) string { + switch goos { + case "linux": + return linuxInstructions(caPath) + case "darwin": + return darwinInstructions(caPath) + case "windows": + return windowsInstructions(caPath) + default: + return genericInstructions(caPath) + } +} + +func linuxInstructions(caPath string) string { + var b strings.Builder + fmt.Fprintf(&b, "System trust store (curl, most CLI tools, Chrome/Chromium):\n") + + switch { + case commandExists("trust"): + fmt.Fprintf(&b, " sudo trust anchor --store %s\n", caPath) + case commandExists("update-ca-trust"): + fmt.Fprintf(&b, " sudo cp %s /etc/pki/ca-trust/source/anchors/mitmux-ca.pem\n", caPath) + fmt.Fprintf(&b, " sudo update-ca-trust\n") + case commandExists("update-ca-certificates"): + fmt.Fprintf(&b, " sudo cp %s /usr/local/share/ca-certificates/mitmux-ca.crt\n", caPath) + fmt.Fprintf(&b, " sudo update-ca-certificates\n") + default: + fmt.Fprintf(&b, " No known trust-store tool (trust / update-ca-trust /\n") + fmt.Fprintf(&b, " update-ca-certificates) found on PATH. Check your distro's\n") + fmt.Fprintf(&b, " docs for how it manages /etc/ssl/certs.\n") + } + + fmt.Fprintf(&b, "\nFirefox (and Chrome/Chromium's own NSS store, which doesn't\n") + fmt.Fprintf(&b, "always follow the system trust store on Linux):\n") + if commandExists("certutil") { + fmt.Fprintf(&b, " certutil -d sql:$HOME/.mozilla/firefox/ -A -n mitmux -t \"C,,\" -i %s\n", caPath) + fmt.Fprintf(&b, " (find with: ls ~/.mozilla/firefox | grep default)\n") + } else { + fmt.Fprintf(&b, " Import manually: Settings -> Privacy & Security -> Certificates\n") + fmt.Fprintf(&b, " -> View Certificates -> Authorities -> Import, select %s\n", caPath) + fmt.Fprintf(&b, " (or install nss-tools/libnss3-tools for certutil, which can\n") + fmt.Fprintf(&b, " script this instead)\n") + } + return b.String() +} + +func darwinInstructions(caPath string) string { + var b strings.Builder + fmt.Fprintf(&b, "System-wide (Keychain Access -> System, or via Terminal):\n") + fmt.Fprintf(&b, " sudo security add-trusted-cert -d -r trustRoot \\\n") + fmt.Fprintf(&b, " -k /Library/Keychains/System.keychain %s\n", caPath) + fmt.Fprintf(&b, "\nCurrent user only (no sudo, login keychain):\n") + fmt.Fprintf(&b, " security add-trusted-cert -d -r trustRoot \\\n") + fmt.Fprintf(&b, " -k ~/Library/Keychains/login.keychain-db %s\n", caPath) + fmt.Fprintf(&b, "\nFirefox uses its own certificate store, not the macOS Keychain -\n") + fmt.Fprintf(&b, "import %s manually via Settings -> Privacy & Security ->\n", caPath) + fmt.Fprintf(&b, "Certificates -> View Certificates -> Authorities -> Import.\n") + return b.String() +} + +func windowsInstructions(caPath string) string { + var b strings.Builder + fmt.Fprintf(&b, "From an elevated (Administrator) command prompt:\n") + fmt.Fprintf(&b, " certutil -addstore -f \"ROOT\" %s\n", caPath) + fmt.Fprintf(&b, "\nOr from an elevated PowerShell:\n") + fmt.Fprintf(&b, " Import-Certificate -FilePath %s -CertStoreLocation Cert:\\LocalMachine\\Root\n", caPath) + fmt.Fprintf(&b, "\nFirefox uses its own certificate store, not the Windows store -\n") + fmt.Fprintf(&b, "import %s manually via Settings -> Privacy & Security ->\n", caPath) + fmt.Fprintf(&b, "Certificates -> View Certificates -> Authorities -> Import.\n") + return b.String() +} + +func genericInstructions(caPath string) string { + return fmt.Sprintf("No install steps known for this OS - import %s into your\n"+ + "client's trust store manually (browser certificate settings, or\n"+ + "whatever --cacert / equivalent flag your TLS client offers).\n", caPath) +} + +// CertPath returns the path to the CA certificate PEM file inside dir +// (see EnsureCA), for callers that just need to point a user or a tool +// at it. +func CertPath(dir string) string { + return filepath.Join(dir, certFileName) +} -- cgit v1.2.3