HTTPS Interception

How It Works

Laurel Proxy performs HTTPS interception via a local Certificate Authority (CA). Here is what happens under the hood:

  1. On first startup, Laurel Proxy generates a root CA certificate and private key at ~/.laurel-proxy/ca/
  2. When a client sends a CONNECT request (HTTPS), Laurel Proxy:
    • Accepts the tunnel
    • Generates a per-domain certificate signed by the CA on the fly
    • Terminates TLS with the client using the generated cert
    • Opens a separate TLS connection to the real server
    • Forwards traffic in both directions, capturing it along the way

The MITM TLS socket offers ALPN ['h2', 'http/1.1'] to the client, and the real server is probed separately over its own ALPN handshake -- the two hops negotiate independently, so an HTTP/2 client talking to an HTTP/1.1-only origin (or the reverse) works without any configuration. The origin probe is cached per host:port, but the first request to a given HTTPS origin still costs one extra TLS handshake for that discovery -- invisible to clients, but a real network side effect. SeeHTTP/2 Support for the full picture, including what gets recorded.

Setup

Step 1: Start the proxy

This generates the CA certificate if it does not already exist.

laurel-proxy start

Step 2: Trust the CA certificate

laurel-proxy trust-ca

This runs the platform-specific trust command. See the table below for details on each platform.

Step 3: Route HTTPS traffic through the proxy

# Via explicit proxy flag
curl -x http://127.0.0.1:8080 https://api.example.com/data

# Or enable system-wide proxy (macOS)
laurel-proxy proxy-on

Platform-Specific Trust

PlatformWhat happens
macOSAdds to System Keychain via security add-trusted-cert (requires sudo)
LinuxCopies to /usr/local/share/ca-certificates/ and runs update-ca-certificates (requires sudo)
FirefoxMust be done manually: Settings > Privacy & Security > Certificates > View Certificates > Import ~/.laurel-proxy/ca/ca.crt

Certificate Details

PropertyValue
CA location~/.laurel-proxy/ca/ca.crt and ca.key
CA validity10 years
CA subject"Laurel Proxy CA"
Per-domain cert validity1 year
Key size2048-bit RSA
Signature algorithmSHA-256
Domain cert cacheLRU, default 500 entries (configurable)

iOS Device Inspection

Laurel Proxy can inspect HTTP/HTTPS traffic from an iOS device. Your computer and iOS device must be on the same Wi-Fi network.

Step 1: Start Laurel Proxy on your computer

laurel-proxy start

Step 2: Note your computer's network address

The CLI prints a Network line on startup with your hostname, for example:

  ● Network  http://robins-macbook.local:8081

You can also find your IP manually:

ipconfig getifaddr en0    # macOS
hostname -I | awk '{print $1}'  # Linux

Step 3: Configure the iOS device to use the proxy

  1. Open Settings > Wi-Fi
  2. Tap the (i) icon next to your connected network
  3. Scroll down and tap Configure Proxy
  4. Select Manual
  5. Set Server to your computer's hostname or IP (e.g. robins-macbook.local or 192.168.1.42)
  6. Set Port to 8080
  7. Tap Save

HTTP traffic is now being captured. For HTTPS inspection, continue with the steps below.

Step 4: Install the CA certificate on iOS

Open Safari on your iOS device and navigate to the network address shown in the CLI or web UI:

http://robins-macbook.local:8081/api/ca.crt

Or use the IP directly: http://192.168.1.42:8081/api/ca.crt

You can also open the web UI and tap the CA Cert link in the toolbar. Safari will prompt you to download a configuration profile. Tap Allow.

Step 5: Install the profile

  1. Open Settings > General > VPN & Device Management (or Profiles & Device Management on older iOS)
  2. Tap the Laurel Proxy CA profile
  3. Tap Install and enter your passcode

Step 6: Enable full trust for the certificate

  1. Open Settings > General > About > Certificate Trust Settings
  2. Toggle Enable Full Trust for Laurel Proxy CA
  3. Tap Continue on the warning dialog

HTTPS traffic from the iOS device is now fully inspectable through Laurel Proxy.

Viewing traffic

Open the web UI from any browser:

http://<your-computer-ip>:8081

Or use the CLI:

laurel-proxy requests --tail

Cleanup

When you are done inspecting, remove the proxy from iOS:

  1. Settings > Wi-Fi > (i) > Configure Proxy > Off
  2. Optionally remove the CA profile: Settings > General > VPN & Device Management > Laurel Proxy CA > Remove Profile

On your computer, you can uninstall the CA certificate from your system trust store:

laurel-proxy uninstall-ca
← ConfigurationHTTP/2 Support →