Skip to content

Document host-side trust for custom MITM proxies #708

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
hiroTamada wants to merge 1 commit into
base: main
Choose a base branch
from
+6 −2
Draft

Document host-side trust for custom MITM proxies #708

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions proxies/custom.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -122,9 +122,13 @@ When creating a proxy with authentication, provide the password. The API respons

## MITM TLS

If your custom proxy terminates TLS and re-signs upstream connections, provide its CA certificate bundle in `config.ca_bundle` when you create the proxy. Kernel validates the bundle and installs it in the browser's trust store when you create a browser with that proxy.
If your custom proxy terminates TLS and re-signs upstream connections, provide its CA certificate bundle in `config.ca_bundle` when you create the proxy. Kernel validates and stores the bundle encrypted, then loads it into the host-side egress proxy to verify certificates signed by your custom proxy. Kernel doesn't install your bundle in the browser's trust store. For intercepted HTTPS, the browser trusts Kernel's egress proxy CA instead. TLS verification remains enabled.

The bundle must contain one or more PEM-encoded CA certificates. It is write-only: proxy responses return `has_ca_bundle: true` instead of the certificate contents. You must bind a proxy with a CA bundle when creating the browser; you can't hot-swap it onto a running browser.
The bundle must contain one or more PEM-encoded CA certificates. It is write-only: proxy responses return `has_ca_bundle: true` instead of the certificate contents. You can bind a proxy with a CA bundle when creating a browser or hot-swap it onto a running browser.

<Warning>
TLS connections without HTTP ALPN remain opaque tunnels. If a client receives your custom proxy's certificate over an opaque tunnel, it still needs to trust your CA locally; `config.ca_bundle` doesn't provide that client-side trust.
</Warning>

## Bypass hosts

Expand Down
Loading