Client certificates and custom roots

These settings need WireLens Pro and are on the Mac only, in Settings ▸ Certificate. WireLens for iPhone and Android always signs with its own root and has no client certificates.

Client certificates#

Some servers ask the client for a certificate before they will talk. When WireLens decrypts such a host, it is WireLens talking to the server, and WireLens needs that certificate.

Open Settings ▸ Certificate ▸ Client certificates (mutual TLS) and click Import… next to Add. Enter the Host (a name or a pattern such as *.example.com), optionally a Port, and choose the Certificate. WireLens accepts:

• a PKCS#12 bundle (.p12 or .pfx), with its Passphrase. Remember password keeps the passphrase for later.
• a PEM certificate with its Private key.
• a DER certificate (.cer or .der) with its key.

The private key goes into your Keychain and stays there. Export… writes a copy only after you tick I understand this file contains the private key, as PEM (certificate + key) or PKCS#12 (.p12) with a passphrase. Remove deletes the private key from the Keychain.

Restart capture after importing. Open connections pick the new certificate up when they reconnect.

Server certificate overrides#

Normally WireLens presents a certificate it makes from your root. A server certificate override presents one you already hold instead. Use it when an app expects one specific certificate for a host, and you have that certificate and its key.

Add one under Settings ▸ Certificate ▸ Server certificate overrides with Import…. It takes the same files as a client certificate.

Which certificate wins#

Both lists match hosts by pattern, and the most specific pattern wins:

api.example.com beats *.example.com, which beats *.

An entry with a port beats the same host without one.

Bring your own root#

If your team runs its own certificate authority, WireLens can sign decrypted traffic with it instead of with the certificate it made. Open Settings ▸ Certificate ▸ Custom root (advanced):

1. Next to Certificate or bundle, click Choose… and pick a .p12 bundle or a PEM CA certificate.
2. Enter the bundle's Passphrase, or choose the matching PEM Private key.
3. Click Import… next to Import and activate. The certificate must be a CA and the key must match it.
4. Restart capture. This drops connections signed by the old root.

The certificate is trusted for this user and the private key stays in your Keychain. RSA and ECDSA both work. Use generated root ▸ Revert goes back to the WireLens root and removes the imported key from the Keychain.

Devices that already trust your internal root then trust WireLens with no extra setup, which is usually the point.

Apps that pin their certificates#

A host that refuses the WireLens certificate twice is passed through for the rest of the session. It keeps working, and it is still captured as a tunnel. These settings get past two kinds of pinning:

• Pinned to a CA you control: import that CA as the custom root.
• Pinned to a certificate you hold: add it as a server certificate override for the host.
• Pinned to a key you do not control: no proxy can produce a matching certificate. Leave the host on passthrough.

See Certificate pinning.

From the command line#

wirelens ships inside the app and is not on your PATH until you link it once.

wirelens cert identity list
wirelens cert identity add --host api.example.com --p12 client.p12 --password "$P12_PASSWORD"
wirelens cert identity add --host api.example.com --cert server.pem --key server-key.pem --kind server
wirelens cert identity remove <id>

--kind client (the default) adds a client certificate, and --kind server a server certificate override. --port limits an entry to one port.