The WireLens root certificate

To show you what is inside HTTPS, WireLens presents its own certificate for each host it decrypts. Those certificates are signed by a root certificate that WireLens creates on your device the first time you use it, and your device accepts them only once you trust that root.

The root's private key is generated on your device and stays there. Every Mac and every iPhone has its own root, which is why a certificate installed from one device does nothing for another.

On the Mac#

The first time you open WireLens it offers to install the root. There are two ways:

• Install Automatically… macOS asks for your administrator password, installs the root into the System keychain and trusts it for HTTPS, for every user on the Mac. This is the one to choose unless you have a reason not to. The same action is Certificate ▸ Install for All Users….
• Install for This User… Installs into your login keychain. You can also export the PEM and drag it into Keychain Access, open it, expand Trust and set When using this certificate to Always Trust.

The Certificate menu and Settings ▸ Certificate show whether the root is missing, installed but not trusted, or trusted. That status is measured, not assumed.

Browsers and runtimes with their own trust store#

Safari, Chrome, Edge, Arc and most native Mac apps use the macOS keychain, so there is nothing more to do. The rest need to be told:

Client setup has copy-paste versions of each, and Tools ▸ Client Setup fills in the exact paths on your Mac.

On iPhone and iPad#

1. Open WireLens and follow Setup. Capture needs to be running so WireLens can serve the certificate.
2. Tap Install Certificate. iOS asks whether to allow a configuration profile download. Tap Allow.
3. Open Settings, tap Profile Downloaded near the top, then Install.
4. Go to Settings ▸ General ▸ About ▸ Certificate Trust Settings and switch on WireLens Root CA.
5. Return to WireLens. Setup notices the trust by itself and restarts capture so decryption begins.

Step 4 is the one people miss: iOS installs the profile without trusting it for TLS until you turn on full trust.

While capture runs you can also open http://wire.lens/ in Safari to reach the install page. Other browsers show a notice asking you to open it in Safari, because only Safari hands the profile to Settings.

An iPhone that uses your Mac as its proxy#

In that setup the iPhone needs the Mac's root, not its own. See Capture other devices.

Export, regenerate and remove#

• Export. Certificate ▸ Export Root Certificate PEM… or DER… on the Mac.
• Regenerate. Creates a new root. Everything that trusted the old one must trust the new one, so only do it if you have a reason.
• Remove. On the Mac, Certificate ▸ Remove Certificate from Keychain…. On iPhone, Settings ▸ General ▸ VPN & Device Management, select the WireLens profile, then Remove Profile.

If you stop using WireLens, remove the trust. Your root never leaves your device, but there is no reason to keep trusting a certificate you are not using.

Bring your own root#

Teams that already run an internal CA can import their own root from a PKCS#12 file instead of using the generated one. See Client certificates and custom roots.