Root certificate

Cloak Proxy decrypts HTTPS by presenting certificates it signs with its own root certificate. Your Mac, and every device you debug, must trust that root certificate for decryption to work. This page covers trusting it, removing and replacing it, using your own certificate authority, and the related TLS settings: client certificates for mutual TLS and key logging for Wireshark.

About the root certificate

Cloak Proxy creates the root certificate on your Mac the first time it opens. Nobody else has the same one.

Property	Value
Name	Cloak Proxy CA ( your Mac’s name, the creation date ), organization Cloak Proxy
Key	ECDSA P-256
Valid for	10 years
Certificate file	~/Library/Application Support/CloakProxy/cloak-proxy-ca.pem
Private key file	~/Library/Application Support/CloakProxy/cloak-proxy-ca-key.pem, readable only by your user

For each host it decrypts, Cloak Proxy signs a certificate for that host name (or IP address) that’s valid for one year.

Protect the private key

Anyone with cloak-proxy-ca-key.pem can create certificates that your Mac, and every device that trusts this certificate, accept for any website. They could read traffic you thought was private. The key never leaves your Mac unless you copy it. Don’t share it, don’t commit it to a repository, and regenerate the certificate if you think it was exposed.

Install and trust it on this Mac

1. Click Install & Trust… in the orange banner above the traffic list, or in Cloak Proxy › Settings… › Certificate.

2. macOS asks you to confirm changing your certificate trust settings. Enter your password or use Touch ID.

   Cloak Proxy adds the certificate to your login keychain and marks it as a trusted root.

3. Check the result: the banner disappears, Settings › Certificate shows Trusted on this Mac, and the status bar shows CA trusted.

Trusting the certificate on this Mac covers Safari, Chrome and other apps that use the macOS keychain. Some runtimes keep their own list of trusted certificates. See Terminal and runtimes and Java, Firefox, Docker, Flutter and Electron. For phones and simulators, see Devices.

Certificate settings

Cloak Proxy › Settings… › Certificate shows the certificate and every action for it.

123456

Settings › Certificate.

1. Whether this Mac trusts the certificate
2. Install & Trust…, or Re-install once trusted
3. Remove the certificate from the login keychain
4. Create a new certificate and key
5. Use your own certificate authority
6. Client certificates for servers that require mutual TLS

×

Item	What it does
Name	The certificate’s common name. Look for it under this name in Keychain Access or on a device.
File	Where the certificate file is.
Status	Trusted on this Mac or Not trusted.
Install & Trust… / Re-install	Adds the certificate to your login keychain as a trusted root. Shows Re-install once it’s trusted; use it if trust was changed in Keychain Access.
Remove from Keychain	Removes the trust setting and deletes every Cloak Proxy CA from your login keychain. Available while the certificate is trusted.
Show in Finder	Reveals cloak-proxy-ca.pem in Finder, for example to drag it to a simulator.
Copy PEM	Copies the certificate (not the key) as PEM text.
Regenerate Certificate…	Creates a new certificate and key. See Regenerate the certificate.
Use My Own CA…	Replaces the certificate with your own. See Use your own CA.
Check Again	Checks the trust status again, for example after you changed it in Keychain Access.

Get the certificate file

Need	How
The file on this Mac	Show in Finder, or run cloakctl ca, which prints the certificate’s path (and creates it if needed).
The PEM text	Copy PEM.
From an AI assistant	The MCP tool certificate_info returns the file path, whether macOS trusts it, and the PEM. Trusting or removing it still needs your password in the app. See MCP server.
On a phone or another computer	With the device set to use Cloak Proxy, open http://cloak.proxy in its browser. The page offers Download certificate (PEM, iOS / macOS) at /cert.pem and Download certificate (DER, Android / Windows) at /cert.crt. Once other devices may connect, you can also open http://192.168.1.20:9090/ (your Mac’s address and port) directly. See Other devices and access control.

cert.cloak and cloakproxy.local work like cloak.proxy.

Remove the certificate

Remove the certificate from your Mac when you stop using Cloak Proxy or when you want HTTPS interception to be impossible.

1. Open Cloak Proxy › Settings… › Certificate.

2. Click Remove from Keychain and confirm with your password if macOS asks.

   The status changes to Not trusted, and the banner comes back.

This removes the certificate from your Mac’s keychain only. The certificate and key files stay in ~/Library/Application Support/CloakProxy, and devices you installed the certificate on still trust it until you remove it there. See Uninstall Cloak Proxy completely.

While the certificate isn’t trusted, Cloak Proxy still records plain HTTP and lists encrypted tunnels. Decrypted hosts fail with a TLS handshake error, because apps reject the certificate.

Regenerate the certificate

Regenerating creates a brand-new root certificate and private key and throws the old ones away. Do it if the key may have been exposed, or to start fresh.

1. Open Cloak Proxy › Settings… › Certificate and click Regenerate Certificate….

2. Confirm with Regenerate in the dialog Regenerate the root certificate?

   Cloak Proxy removes the old certificate from your login keychain, writes the new certificate and key, and restarts the proxy.

3. Click Install & Trust… to trust the new certificate on this Mac.

4. Install the new certificate on every device and simulator you debug, and remove the old one there.

Caution

After you regenerate, devices and simulators that trusted the old certificate reject Cloak Proxy until you install the new one. The dialog reminds you: Devices and simulators that trust the current certificate will need the new one installed.

Use your own CA

If your team already has a debugging certificate authority, or your test devices are managed with one, Cloak Proxy can sign with it instead of its own.

Requirements:

• The certificate and its private key, as two PEM files.
• The key must be an ECDSA P-256 (EC) key. RSA keys aren’t supported.
• The key must belong to the certificate.

1. Back up ~/Library/Application Support/CloakProxy/cloak-proxy-ca.pem and cloak-proxy-ca-key.pem if you might want Cloak Proxy’s own certificate back. Your CA replaces those two files.

2. Open Cloak Proxy › Settings… › Certificate and click Use My Own CA….

3. In the panel Choose your root certificate (PEM), then its private key (PEM), select both files at once (⌘-click the second) and click Open.

   Cloak Proxy recognizes which file is which from its contents, saves them, and restarts the proxy.

4. If the status shows Not trusted, click Install & Trust….

Message	Meaning
Choose both the certificate and its private key (select both files at once). They must be PEM files.	Only one file was selected, or one of them isn’t PEM.
Couldn’t use that certificate: Only P-256 (EC) private keys are supported right now.	The key is RSA or another type.
Couldn’t use that certificate: The private key doesn’t belong to that certificate.	The two files don’t match.

To go back to a Cloak Proxy certificate, restore your backup files and reopen Cloak Proxy, or click Regenerate Certificate… for a new one.

A shared CA is a shared risk

Every device that trusts your CA trusts anything signed with its key. Keep the key on as few machines as possible, and never use a CA that real production devices or customers trust.

Present client certificates (mutual TLS)

Some servers require the client to present a certificate (mutual TLS, or mTLS). Cloak Proxy opens its own connection to the server, so it presents the certificate on the app’s behalf.

1. Open Cloak Proxy › Settings… › Certificate and click Add Client Certificate under Client certificates (mutual TLS).

2. In Host (e.g. mtls.example.com), enter the host or a pattern such as *.internal.example.com.

3. Enter the path of the .p12 or .pfx file that holds the certificate and its private key, or click Choose….

4. Enter the file’s password in Password for the .p12 file.

Field	What it does
Switch	Turns the rule on or off.
Host (e.g. mtls.example.com)	Which servers get this certificate. Uses the same patterns as SSL Proxying.
Path and Choose…	The .p12 or .pfx file. A ~ at the start means your home folder.
Password for the .p12 file	The file’s password.
Minus button	Deletes the rule.

Changes apply at once. When a request goes to a matching host, Cloak Proxy presents the certificate and labels the request Client Certificate in the traffic list’s Path column. The first enabled rule that matches wins. If the file can’t be loaded, the request fails with Couldn’t load the client certificate followed by the path and the reason.

Client certificates apply to HTTPS requests that Cloak Proxy decrypts and sends on, including requests you repeat or compose. Encrypted tunnels that Cloak Proxy only relays go straight from the app to the server, so Cloak Proxy can’t add a certificate to them. Turn on SSL Proxying for the host so its requests are decrypted.

Caution

The client certificate’s password is saved with Cloak Proxy’s settings in its preferences file. Use a certificate issued for testing, not one that grants production access.

Write TLS keys for Wireshark

TLS key logging writes the session secrets of every TLS connection Cloak Proxy makes to a file in the SSLKEYLOGFILE format. Wireshark reads that file to decrypt a packet capture of the same traffic, which helps when you need to look below HTTP.

1

Settings › Advanced.

1. Write TLS keys for Wireshark

×

1. Open Cloak Proxy › Settings… › Advanced and turn on Write TLS keys for Wireshark.

   The Key log file field appears with the default path ~/Desktop/cloak-proxy-sslkeys.log. Change it if you like.

2. In Wireshark, open Settings › Protocols › TLS and set (Pre)-Master-Secret log filename to the same file.

3. Capture traffic in Wireshark while Cloak Proxy decrypts it.

4. When you’re done, turn the switch off and delete the key log file.

Cloak Proxy logs keys for both sides of each decrypted connection: the app’s connection to Cloak Proxy and Cloak Proxy’s connection to the server. The file is created readable only by your user, and new keys are added to the end of it.

For a headless proxy, cloakctl run --keylog FILE does the same. See cloakctl.

The key log decrypts your captures

Anyone with the key log file can decrypt the matching packet captures. Delete it when you’re done, and never share it alongside a capture.

Related

SSL ProxyingChoose which hosts and apps are decrypted.

Other devices and access controlThe certificate page and QR code for devices.

Network settingsInsecure upstream hosts, external proxies and more.

Security and privacyThe certificate key, the API token and more.