Certificates & HTTPS interception

A traditional HTTP proxy cannot transparently forward HTTPS without the client knowing — the browser will reject the man-in-the-middle. RelayCore performs transparent HTTPS interception by dynamically issuing certificates: the client connects to RelayCore using a RelayCore-signed certificate (which the client must trust), and RelayCore in turn speaks real HTTPS to the upstream server.

For this to work, you must first generate a CA certificate and install it into the client's trust store.

Default storage

All CA files live in the data directory (default ~/.relay-core):

  • ca_cert.pem — CA certificate
  • ca_key.pem — CA private key
  • ca_cert.json — CA metadata (required for persistent load)

Override the default paths with RELAY_CA_CERT / RELAY_CA_KEY (must be set as a pair). The run command will fail fast with an actionable error if the CA is missing.

Quick flow

# 1. Generate the CA (once)
relay-core-cli ca generate

# 2. Install into the system trust store
relay-core-cli ca install   # macOS auto; other platforms see below

# 3. Start the proxy
relay-core-cli run

ca subcommands

relay-core-cli ca <subcommand>

  generate [--force]        Generate the CA (--force to overwrite)
  install                   Install into the system trust store
  uninstall                 Remove from the system trust store
  status                    Show paths, presence, and trust status
  export [-o PATH] [--der]  Export the certificate; --der produces a Windows .cer

Platform notes

macOS

ca install writes the CA to the system keychain, cleaning up any stale RelayCraft CA entries first to avoid leftover fingerprint conflicts.

ca status compares the local certificate against the keychain entry by SHA-1:

$ relay-core-cli ca status
CA cert: /Users/me/.relay-core/ca_cert.pem
CA key:  /Users/me/.relay-core/ca_key.pem
Trusted in keychain: yes
Keychain SHA-1:       12:34:56:78:9a:bc:de:f0:12:34:56:78:9a:bc:de:f0:12:34:56:78
Local cert SHA-1:     12:34:56:78:9a:bc:de:f0:12:34:56:78:9a:bc:de:f0:12:34:56:78
Match:                OK

If the report says Match: MISMATCH, the CA was regenerated but not reinstalled — re-run ca install.

Linux

No automated install step. Manual:

# Debian / Ubuntu
sudo cp ~/.relay-core/ca_cert.pem /usr/local/share/ca-certificates/relay-core.crt
sudo update-ca-certificates

# RHEL / Fedora
sudo cp ~/.relay-core/ca_cert.pem /etc/pki/ca-trust/source/anchors/relay-core.crt
sudo update-ca-trust

# Arch
sudo trust anchor ~/.relay-core/ca_cert.pem

# Verify
curl -vI https://example.com --proxy http://127.0.0.1:8080

Windows

Export a binary .cer with --der:

relay-core-cli ca export -o relay-core.cer --der

Double-click the .cer → "Install Certificate" → "Local Machine" → "Place all certificates in the following store" → "Trusted Root Certification Authorities". PowerShell equivalent:

Import-Certificate -FilePath .\relay-core.cer `
  -CertStoreLocation Cert:\LocalMachine\Root

Firefox / per-browser trust stores

Firefox maintains its own CA trust store and does not use the system one. In Settings → Privacy & Security → Certificates → View Certificates → Import, import ca_cert.pem and check "Trust this CA to identify websites".

CI & container environments

  • Bake ca_cert.pem into your Docker image at /usr/local/share/ca-certificates/ and run update-ca-certificates in the Dockerfile.
  • For CI runners that need HTTPS interception, use ca export --der to feed the certificate into the runner's trust store.
  • Run ca install --help for conflict-resolution details when multiple proxies coexist.

Uninstalling

# macOS
relay-core-cli ca uninstall

# Linux
sudo rm /usr/local/share/ca-certificates/relay-core.crt
sudo update-ca-certificates --fresh

After uninstall, HTTPS sites will show certificate errors — this is expected, and proves the CA was doing its job.