TLS & certificates

Impostor uses rustls for a clean TLS and mutual-TLS story. Client certificates are registered per host — a certificate is issued for a server, so it belongs to that server rather than to a folder in your workspace.

Registering a certificate

Open Certificates — from the ☰ menu, the macOS menu bar, or the command palette (⌘K / Ctrl+K) — and add an entry. Each entry has a host pattern and the TLS material to present to it:

Any request that reaches a matching host presents that identity — HTTP, WebSocket, SSE, gRPC and MCP alike, wherever the request sits in the workspace tree. Move a request between folders and nothing changes.

Certificates live in certificates.json in your OS app-data directory, outside any workspace: cert paths are machine-specific, and a workspace you share must never be able to point someone else’s requests at a local file. The command line and the MCP server read the same file, so they present the same identities as the app.

How a host is matched

The most specific entry wins:

Two details worth knowing:

• An entry that names a port applies only to that port. A certificate for localhost:8443 is not presented to localhost:8444.
• A wildcard covers sub-domains (api.acme.com, a.b.acme.com) but not the bare domain acme.com. Add a second entry if you need both.

Between two matching wildcards the longer pattern wins, so *.eu.acme.com beats *.acme.com. Entries you switch off are skipped without being deleted.

Custom Certificate Authorities

For self-signed servers or internal enterprise endpoints, set just the CA bundle on an entry — a client identity is optional. The bundle is added to the system roots rather than replacing them.

Client mTLS

Supply your client identity either as a PEM certificate paired with a PKCS#8 key, or as a bundled PKCS#12 (.p12 / .pfx) file. For PKCS#12 the key travels inside the bundle, so the key fields don’t apply and only its password is asked for.

Where the key comes from

The Client key field has two modes:

• File — a path to the key on disk, the usual case.
• Paste — the PEM key text itself, for a key that doesn’t live on disk (handed to you in a password manager, say, or minted by a script). A pasted key is a credential, so it is moved into Impostor’s encrypted vault on save; only a reference to it is written to certificates.json, and reopening the entry shows •••••• (stored encrypted) rather than the key.

Only one mode is in play at a time — switching clears the other, so a stale path can never quietly win over the key you pasted.

Encrypted keys

A key encrypted at rest (-----BEGIN ENCRYPTED PRIVATE KEY-----) is decrypted with the Key password before the handshake. Leave that field empty for an unencrypted key. Like the PKCS#12 password, it is stored in the vault, never in the file.

PKCS#8 encryption (PBES2) is what openssl pkcs8 -topk8 and modern tooling produce, and is what’s supported. OpenSSL’s traditional PEM encryption — a Proc-Type: 4,ENCRYPTED header on a BEGIN RSA PRIVATE KEY block — is a long-deprecated scheme built on an MD5 key derivation; Impostor detects it and tells you the one-line conversion:

openssl pkcs8 -topk8 -in key.pem -out key-pkcs8.pem

Per-request overrides

A request can still carry its own certificate on its Cert tab, which wins over any registered entry for that request only. This is the escape hatch for one-off debugging — flipping insecureSkipVerify on a single request, or trying a second identity against the same host — not the place for configuration you want to keep.

When a registered certificate applies, the Cert tab says which entry matched and shows a read-only Registered certificate panel; the gRPC editor’s TLS / mTLS section does the same and expands automatically. The tab’s filled dot means this request overrides with its own certificate, a hollow ring means it is using a registered one.

Certificate paths support variables, so {{workspaceDir}}/certs/client.p12 resolves against whichever workspace is open.

Insecure connections

For testing environments where certificate validation is not feasible, you can toggle the insecureSkipVerify option to bypass standard TLS checks — on a registered entry, or on a single request from its Cert tab. When a request is sent with TLS verification disabled, a clear warning is surfaced in the response logs to ensure this state is visible. Note that this option is currently not supported for gRPC requests.