iPhone and iPad

To debug an app on a real iPhone or iPad, point the device’s Wi-Fi proxy at your Mac and install the Cloak Proxy certificate on it. The device and the Mac must be on the same Wi-Fi network. The iPhone & iPad tab of Device & Runtime Setup shows your Mac’s address, the port and a QR code for the certificate.

1234

The iPhone & iPad tab. The warning and button appear only while other devices can't connect.

1. Lets other devices connect and restarts the proxy
2. The Server and Port to enter on the iPhone
3. QR code that opens the certificate page on the iPhone
4. The certificate page address to open in Safari

×

Before you start

• Your Mac and the iPhone or iPad are on the same Wi-Fi network, and the network lets devices reach each other. Guest networks and some office networks block this.
• Cloak Proxy is running. It doesn’t need the macOS proxy on to capture a device.
• You know which hosts you want to decrypt. Add them in SSL Proxying, or HTTPS from the device passes through encrypted.

Let the device connect

By default Cloak Proxy only accepts connections from your Mac. When that’s the case, the iPhone & iPad tab shows Other devices can’t connect yet.

1. Open Device & Runtime Setup (click Devices in the toolbar) and choose the iPhone & iPad tab.

2. Click Allow Other Devices to Connect.

   Cloak Proxy turns on Allow other devices to connect (phones, other computers) and restarts the proxy right away. If the macOS proxy was on, it’s turned off and back on during the restart. The warning disappears.

You can also turn this on in Settings › General. To accept only your iPhone, add its address to Allowed devices in Settings › Network. See Other devices and access control.

Anyone on your network can use the proxy

While other devices may connect, any device on your network can send traffic through Cloak Proxy unless you set up Allowed devices. Turn it off when you finish debugging.

Set the Wi-Fi proxy on the iPhone

The tab’s first section, 1. Set the Wi-Fi proxy on the iPhone, shows the values to enter. Server is your Mac’s IP address on the local network (for example 192.168.1.20) and Port is the port Cloak Proxy listens on (9090 by default). Both are selectable so you can copy them.

1. On the iPhone or iPad, open Settings › Wi-Fi.

2. Tap the ⓘ button next to the network you’re connected to.

3. Scroll down and tap Configure Proxy.

4. Choose Manual.

5. Enter the Server and Port shown in Cloak Proxy. Leave Authentication off.

6. Tap Save.

Open any website on the device. Its requests appear in Cloak Proxy’s traffic list, grouped in the sidebar under the device’s IP address with a phone icon.

Note

Cloak Proxy shows the address of your Mac’s primary network interface (en0, usually Wi-Fi). If your Mac gets a new address, for example after reconnecting to the network, update the Server on the device.

Install the certificate

The tab’s second section, 2. Install the certificate, gives you two ways to open the certificate page.

Scan the QR code

Point the iPhone’s Camera app at the QR code in Cloak Proxy and tap the link that appears. The QR code opens http:// followed by your Mac’s address and port (for example http://192.168.1.20:9090/), so it works even before you set the Wi-Fi proxy, as long as other devices may connect.

Open http://cloak.proxy

After you set the Wi-Fi proxy, open Safari and go to http://cloak.proxy. Cloak Proxy answers this address itself, so it only works while the device’s proxy points at Cloak Proxy.

Both show the same page, titled Cloak Proxy, with two download buttons. Then:

1. Tap Download certificate (PEM, iOS / macOS).

   Safari asks whether to allow the configuration profile to download. Tap Allow, then Close.

2. Open Settings › General › VPN & Device Management. Recent versions of iOS also show a Profile Downloaded item near the top of Settings.

3. Tap the downloaded profile. Its name starts with Cloak Proxy CA, followed by your Mac’s name and the date the certificate was created.

4. Tap Install, enter the device passcode, and confirm with Install again.

5. Open Settings › General › About › Certificate Trust Settings.

6. Under Enable full trust for root certificates, turn on the switch for Cloak Proxy CA, then tap Continue.

Without the last step, iOS installs the profile but apps still reject the certificates Cloak Proxy creates, and HTTPS requests to hosts in SSL Proxying fail.

Install it only on devices you own

The certificate lets Cloak Proxy decrypt HTTPS traffic from the device for the hosts you choose. Install it only on your own devices, or on test devices you have permission to debug, and remove it when you’re done. The certificate page says the same.

Check that it works

1. Add a host your app uses to SSL Proxying, for example api.example.com.

2. Open your app on the device and use the feature you’re debugging.

3. In Cloak Proxy, select the device’s IP address in the sidebar. Requests to api.example.com show their full headers and bodies.

If an app’s requests fail only while the proxy is on, the app may pin its certificates. Pinned apps reject any certificate except their own, and Cloak Proxy can’t decrypt them. Remove the host from SSL Proxying to let that app’s traffic pass through encrypted. See SSL Proxying.

Undo the setup

Remove the proxy and the profile when you’re done. The tab reminds you: Remove the profile and the Wi-Fi proxy when you’re done.

1. On the device, open Settings › Wi-Fi, tap ⓘ next to the network, tap Configure Proxy, choose Off, and tap Save.

   Do this before you quit Cloak Proxy or leave the network. While the proxy points at a Mac where Cloak Proxy isn’t running, the device can’t reach the internet over that Wi-Fi network.

2. Open Settings › General › VPN & Device Management, tap the Cloak Proxy CA profile, tap Remove Profile, and enter the passcode. This also removes it from Certificate Trust Settings.

3. On the Mac, open Settings › General, turn off Allow other devices to connect (phones, other computers), and click Apply & Restart Proxy.

Tip

If you regenerate the root certificate in Settings › Certificate, devices that trusted the old one need the new one installed. Remove the old profile and install the certificate again from http://cloak.proxy.

Troubleshooting

Symptom	What to check
The device can’t load any page	Cloak Proxy is running, Allow other devices to connect is on, the Server and Port match the tab, and the device’s address is in Allowed devices (if you use the list).
The QR code or http://cloak.proxy doesn’t open	The QR code needs other devices to be allowed. http://cloak.proxy also needs the Wi-Fi proxy set.
HTTPS requests show as tunnels	The host isn’t in SSL Proxying.
HTTPS requests fail with a certificate error	Full trust isn’t turned on in Certificate Trust Settings, or the app pins its certificates.
Nothing appears for one app	The app may not use the system proxy. See Apps that ignore the proxy.

For more, see Troubleshooting.

Related

Other devices and access controlRestrict which devices can connect, and the certificate page.

SSL ProxyingChoose which hosts are decrypted.

iOS SimulatorCapture simulators without a Wi-Fi proxy.

Debug a mobile appA full walkthrough on a real device.