iOS Simulator

Simulators are the quickest way to debug an iOS app’s network calls. iOS, tvOS and watchOS Simulators use your Mac’s network settings, so their traffic is captured whenever the macOS proxy is on. Each simulator keeps its own trusted certificates, though, so it needs the Cloak Proxy certificate installed once before HTTPS can be decrypted.

Requirements

• Xcode, installed and selected as the active developer directory. The one-click install uses simctl, which comes with Xcode.
• At least one simulator booted (running) when you install the certificate.
• The macOS proxy on, so the simulator’s traffic goes through Cloak Proxy. See macOS traffic.

If simctl isn’t available, the iOS Simulator tab shows: This needs Xcode (simctl isn’t installed). Install Xcode from the App Store, then run sudo xcode-select -s /Applications/Xcode.app.

12

The iOS Simulator tab on a Mac without Xcode. With Xcode installed, the warning is replaced by the install button.

1. The iOS Simulator tab
2. Shown when simctl isn't found; install Xcode and select it

×

Terminal

sudo xcode-select -s /Applications/Xcode.app

Cloak Proxy checks for simctl each time you open the tab, so switch to another tab and back after you install Xcode.

Install the certificate

1. Boot the simulators you want to use. Open them from Xcode or the Simulator app.

2. Open Device & Runtime Setup (click Devices in the toolbar) and choose the iOS Simulator tab.

3. Click Install Certificate on All Booted Simulators.

   Cloak Proxy runs this command with the path of its root certificate:

   xcrun simctl keychain booted add-root-cert "$HOME/Library/Application Support/CloakProxy/cloak-proxy-ca.pem"

4. Read the result below the button:

   • Installed. Restart the app in the simulator. The certificate is trusted. Quit and reopen your app so it picks up the change.
   • simctl: no booted simulator? No simulator was running. Boot one and click the button again.
   • simctl: followed by other text is the error simctl reported.

5. Turn on the macOS proxy if it’s off: click macOS Proxy in the toolbar or press ⇧ ⌘ P.

You don’t need to set a proxy inside the simulator or turn on Allow other devices to connect. The simulator’s requests come from your Mac itself, the same way any other Mac app’s do.

Tip

The certificate stays installed until you erase the simulator. A new simulator, or one you erase with Device › Erase All Content and Settings, needs it installed again.

Install on one specific simulator

To install the certificate on one particular simulator while several are booted, run simctl yourself with that simulator’s UDID. List the UDIDs first; booted simulators are marked (Booted).

Terminal

xcrun simctl list devices
xcrun simctl keychain <UDID> add-root-cert "$HOME/Library/Application Support/CloakProxy/cloak-proxy-ca.pem"

To print the certificate’s path from a script, use cloakctl ca. See cloakctl.

Decrypt the hosts you need

Installing the certificate makes decryption possible. Cloak Proxy still decrypts only the hosts in SSL Proxying, or the apps you turned SSL Proxying on for. Add your API’s host, for example api.example.com, then repeat the request in the simulator.

Note

Hosts in the Bypass list skip Cloak Proxy entirely, in simulators too, because simulators use the Mac’s proxy settings. The defaults bypass localhost, *.local and 169.254/16.

Undo the setup

1. Turn off the macOS proxy when you no longer want to capture (⇧ ⌘ P). Simulators then connect directly again.

2. To remove the certificate from a simulator, reset its keychain or erase it:

   Terminal

   xcrun simctl keychain booted reset

   Resetting removes every certificate you added to that simulator’s keychain, not only Cloak Proxy’s. Device › Erase All Content and Settings in the Simulator app removes everything.

If you regenerate the root certificate in Settings › Certificate, simulators that trusted the old one need the new one installed. Click Install Certificate on All Booted Simulators again.

Related

macOS trafficTurn the macOS proxy on and off.

SSL ProxyingChoose which hosts are decrypted.

iPhone and iPadCapture a real device over Wi-Fi.

CertificateInstall, remove or regenerate the root certificate.