iOS Platform Guide¶

This guide covers iOS-specific setup, considerations, and best practices for using friTap on iOS devices.

What friTap can and cannot see on iOS¶

friTap hooks TLS libraries, not Apple's networking APIs. The distinction that matters is which TLS implementation an app ends up in:

How key extraction works on iOS¶

Apple does not export SSL_CTX_set_keylog_callback. friTap therefore hooks the exported SSL_CTX_set_info_callback and writes its own keylog callback directly into the live SSL_CTX struct at a byte offset.

That offset is load-bearing: a wrong value clobbers a neighbouring field and kills the target process. friTap derives it at run time from the target's own binary by disassembling the non-exported setter and decoding the immediate in its two-instruction body:

_SSL_CTX_set_keylog_callback:
    str x1, [x0, #0x310]      ; ctx->keylog_callback = cb
    ret

A per-OS-version table is the fallback when that decode is not possible.

Prerequisites¶

Device requirements¶

• Jailbroken iOS device. A jailbreak is genuinely required: the friTap CLI has no Frida Gadget / jailed-app code path.
• arm64 only. Load-bearing, not incidental: the offset derivation decodes arm64 instructions.
• frida-server running on the device.
• USB connection (via usbmuxd) or SSH access.

Checking jailed vs jailbroken¶

frida-ps -Uai

If this lists your installed applications, frida-server is reachable and the device is usable. If it errors out or lists nothing, fix that before touching friTap.

iOS version support¶

There is no version gate anywhere in friTap's code. What actually varies by version is the SSL_CTX.keylog_callback offset used as fallback:

iOS 14 through 26 each have their own bucket. iOS 13 and earlier share one never-measured value and should be treated as untested.

Host machine setup¶

# macOS
brew install usbmuxd
brew install libimobiledevice

# Linux
sudo apt install usbmuxd libimobiledevice-tools

# frida tooling
pip3 install frida-tools

libimobiledevice provides iproxy (USB port forwarding) and idevicecrashreport, which friTap uses to pull crash reports after an instrumented target dies (see iOS crash reporting).

Device Setup¶

Jailbreak tools¶

The four legacy tools all cap out at iOS 14.8.1. friTap carries measured or field-reported offsets for iOS 17, 18 and 26, so a modern rootless jailbreak is the normal setup today.

Rootless jailbreaks¶

On a rootless jailbreak the entire bootstrap prefix moves under /var/jb:

/var/jb/usr/sbin/frida-server     # not /usr/sbin/frida-server
/var/jb/Applications/Sileo.app    # Sileo / Zebra live under the prefix too

Install Frida on the device¶

# Method 1: via Sileo / Zebra / Cydia
#   Add the Frida repository: https://build.frida.re
#   Install the "Frida" package

# Method 2: manual, over SSH
ssh root@<device-ip>
apt update
apt install re.frida.server

SSH setup (optional)¶

# Install OpenSSH via Sileo/Zebra/Cydia
# Default credentials (CHANGE IMMEDIATELY):
#   Username: root
#   Password: alpine

ssh root@<device-ip>

# Change the default password before doing anything else
passwd root

USB connection setup¶

# Forward the frida-server port over USB.
# Modern libimobiledevice syntax is LOCAL:REMOTE
iproxy 27042:27042

# friTap's own server manager expects SSH on forwarded port 2222
iproxy 2222:22

# Verify
frida-ls-devices

Frida Server Management¶

Starting frida-server¶

# Rootful jailbreak
ssh root@<device-ip>
frida-server &

# Rootless jailbreak (palera1n rootless, Dopamine, XinaA15)
ssh root@<device-ip>
/var/jb/usr/sbin/frida-server &

Verifying server status¶

# Devices reachable from the host
frida-ls-devices

# Running processes on the device
frida-ps -U

# Installed applications (bundle identifiers)
frida-ps -Uai

friTap Usage on iOS¶

Basic analysis¶

# The canonical iOS invocation: attach, extract keys
fritap -m -k keys.log com.example.app

# Verbose plus debug output
fritap -m -v -do com.example.app

# Metadata about which libraries were hooked
fritap -m -k keys.log -j metadata.json com.example.app

Attach mode is the default. Add -s/--spawn only when you need it.

App identification¶

# List running apps
frida-ps -Ua

# List installed apps with bundle identifiers
frida-ps -Uai

# Find a specific app (write to a file first, see the piping note below)
frida-ps -Uai > apps.txt
grep -i instagram apps.txt

# Then target the bundle identifier
fritap -m -k keys.log com.burbn.instagram

# Works, but only what scrolls past — and nothing without the 2>&1
fritap -m -v com.example.app 2>&1 | grep -i ssl

# Better
fritap -m -v com.example.app > fritap.log 2>&1
grep -i ssl fritap.log

Spawn mode¶

# Start the app fresh under friTap control, capturing startup TLS
fritap -m -s -k keys.log com.example.app

Spawn mode gets the keylog hook live before the app resumes, which matters for TLS that happens during launch. It is not a pinning bypass and not a crash workaround; if a spawn crashes, try attach mode instead (see Debugging agent-load crashes).

Packet capture does not work on iOS¶

Use this workflow instead:

# 1. Capture keys with friTap
fritap -m -k keys.log com.example.app

# 2. Capture packets separately (host-side, upstream router, tcpdump on a
#    gateway, a Wi-Fi capture, etc.) into traffic.pcap

# 3. In Wireshark:
#    Preferences -> Protocols -> TLS -> (Pre)-Master-Secret log filename
#    -> point it at keys.log, then open traffic.pcap

SSL/TLS Libraries on iOS¶

Six TLS libraries are registered for iOS (agent/platforms/ios.ts). The socket library is libSystem.B.dylib.

There is no QUIC support on iOS, and no NSS, GnuTLS, mbedTLS or wolfSSL.

Pattern-based hooking on iOS¶

--patterns accepts an ios platform key, but be aware:

# Absolute path recommended
fritap -m --patterns /abs/path/to/ios_patterns.json -k keys.log com.example.app

A missing --patterns file is silently ignored. An invalid one warns and falls back to defaults. Neither case is loud, so verify with -do that your patterns were actually loaded.

Library detection¶

fritap -m -do -v com.example.app > fritap.log 2>&1
grep -i ssl fritap.log

With -j metadata.json, the libraries_detected array lists only libraries friTap actually hooked. On iOS that means one or more of BoringSSL, LibreSSL, OpenSSL, OpenSSL/BoringSSL, Cronet, Flutter BoringSSL — nothing else can ever appear there.

Limitations¶

• No plaintext interception. Keylog extraction only.
• Socket FD unavailable. friTap cannot recover the socket from an SSL_read/SSL_write on Apple, so there is no 5-tuple and no pcap framing.
• No SecureTransport / libcoretls support. Legacy Security.framework TLS is not hooked at all.
• No QUIC support.

Certificate Pinning on iOS¶

friTap has no certificate-pinning bypass hooks of any kind. If you need to intercept and modify traffic rather than just decrypt a recording, that is a proxy job:

# Redirect connections to a proxy (e.g. mitmproxy).
# Requires the separate fritap-proxy package.
fritap -m --proxy 127.0.0.1:8080 com.example.app

Two things that are frequently mistaken for pinning bypasses and are not:

• --enable_default_fd has nothing to do with pinning. It fabricates a placeholder 5-tuple (127.0.0.1:1234-127.0.0.1:2345) so pcap framing has something to write when the socket FD cannot be determined. On iOS, where there is no pcap output anyway, it changes nothing useful.
• Spawn mode (-s) is not a bypass. It only makes hooks live earlier.

Flags that behave differently on iOS¶

-t/--timeout¶

--timeout is unrelated to --script-load-timeout.

--script-load-timeout <seconds>¶

Bounds Frida's script.load(), i.e. how long friTap waits for the agent to finish starting up inside the target.

• Default: 20 seconds.
• Any non-positive value disables the bound (--script-load-timeout 0).
• Automatically tripled when --patterns, --library-scan or --scan-keys-region is used, since those scan during agent startup.

--offsets¶

-c/--custom_script¶

fritap -m -c /abs/path/to/my_script.js -k keys.log com.example.app

-do/--debug-output and --debug-log¶

-do enables debug output and silently writes ./fritap_debug_<ts>_<pid>.log into the current working directory. Use --debug-log <path> to choose the location explicitly.

fritap -m -do --debug-log /tmp/fritap_ios.log -k keys.log com.example.app

The rebuild rule¶

./dev/compile_agent.sh

[compile_agent.sh] done. Agent: <bytes> bytes

FRITAP_AGENT_BUNDLE¶

This environment variable overrides which bundle gets loaded. It is the clean A/B lever when you want to compare a modified agent against the shipped one:

FRITAP_AGENT_BUNDLE=/abs/path/to/my_fritap_agent.js \
    fritap -m -do -k keys.log com.example.app

Precedence, highest first:

1. FRITAP_AGENT_BUNDLE (not ABI-filtered)
2. ABI-matched fritap.agent_bundle entry point
3. The shipped bundle

Debugging agent-load crashes¶

If the target dies during instrumentation, bisect in this order rather than guessing.

(a) --probe first. It loads the agent, reports which platform code path friTap selected, and installs no TLS hooks, producing no keys, pcap or plaintext.

fritap -m --probe com.example.app

If the target survives --probe, the agent bootstrap is fine and the crash is in hook installation.

(b) Attach instead of spawn. Drop -s:

fritap -m -k keys.log com.example.app

(c) Try --modern.

fritap -m --modern -k keys.log com.example.app

--modern does not write into the SSL_CTX struct at all. So if the target survives under --modern but dies without it, that points at a wrong struct offset.

(d) Collect the diagnostics.

fritap -m -do --debug-log /tmp/fritap_ios.log -k keys.log com.example.app

Report the printed line:

Agent platform report: <platform> (target=<target>, agent ABI <N>)

plus the chosen SSL_CTX.keylog_callback offset and its stated provenance.

iOS crash reporting¶

When an instrumented target dies, friTap can pull and decode the device's ReportCrash .ips report via idevicecrashreport (over usbmuxd, so no device-side SSH or root shell is needed; reports are pulled with -k, keeping the on-device copy).

Decoded exception types and what they usually mean:

Reports live on the device at /var/mobile/Library/Logs/CrashReporter, including on rootless jailbreaks.

Reporting an iOS bug¶

Include all of the following. The first item is the one people get wrong:

• kern.osproductversion, exactly as printed. This is what the offset code reads — not uname -a.

# On the device
sysctl -n kern.osproductversion

• The Agent platform report: line from -do output.
• Whether this is a git checkout or a PyPI install, and if a checkout, whether you recompiled the agent (./dev/compile_agent.sh, including the done. Agent: <bytes> line). See The rebuild rule.
• Jailbreak type: which tool, and rootful or rootless.
• The .ips crash report, if the target died.
• The exact friTap command line and the target bundle identifier.

Troubleshooting iOS Issues¶

Connection problems¶

# Device not detected
frida-ls-devices

# Restart usbmuxd (macOS/Linux)
sudo pkill usbmuxd
sudo usbmuxd

# Restart frida-server on the device
ssh root@<device-ip>
killall frida-server
frida-server &            # rootless: /var/jb/usr/sbin/frida-server &

frida-server issues¶

ssh root@<device-ip>
ps aux | grep frida-server

killall frida-server
frida-server &

# Port conflicts
netstat -an | grep 27042

App analysis issues¶

# Attach mode is the default when you omit -s/--spawn
fritap -m -k keys.log com.example.app

# Confirm the app is actually running / installed
frida-ps -Uai > apps.txt
grep com.example.app apps.txt

If the app crashes when friTap attaches, go to Debugging agent-load crashes.

Monitoring device resources¶

ssh root@<device-ip>

# Darwin's top filters by user with -U (uppercase)
top -U mobile

iOS-Specific Features¶

Background app analysis¶

# Catch newly spawned processes matching the target app
fritap -m --enable_spawn_gating -k keys.log com.example.app

Then background the app and continue exercising it.

App extensions¶

# Extensions (widgets, keyboards, share sheets) are separate processes
fritap -m -k ext_keys.log com.example.app.extension

# Or catch them as they spawn alongside the host app
fritap -m --enable_spawn_gating -k keys.log com.example.app

Security Considerations¶

Device security¶

• Keep jailbreak tools updated
• Change the default SSH password (root / alpine) immediately
• Use trusted networks for analysis
• Disable services you are not using

Analysis safety¶

• Use test accounts for sensitive apps
• Avoid production banking and financial accounts
• Document all analysis activities
• Keep device backups

Legal considerations¶

• Only analyze apps you own or have explicit permission to test
• Respect app store terms of service
• Follow responsible disclosure for vulnerabilities you find
• Comply with local laws and regulations

Wireshark Workflow¶

Since iOS produces no pcap, decryption is a two-source job: friTap supplies the keys, something else supplies the packets.

# 1. Keys from friTap
fritap -m -k keys.log com.example.app

# 2. Packets from anywhere else: a gateway tcpdump, a Wi-Fi capture,
#    an upstream router, a shared-network host capture.

# 3. Wireshark:
#    Preferences -> Protocols -> TLS
#    -> (Pre)-Master-Secret log filename = /path/to/keys.log
#    Then open the pcap.

The keys.log friTap writes for TLS is in the standard NSS SSLKEYLOGFILE format, so any tool that consumes that format can use it directly.

Best Practices for iOS Analysis¶

1. Device preparation¶

• Start from a known-good device state
• Remove artifacts from previous runs
• Confirm frida-server is reachable with frida-ps -Uai before running friTap

2. Analysis methodology¶

# Start minimal
fritap -m -k keys.log com.example.app

# Add diagnostics only when something is wrong
fritap -m -v -do --debug-log /tmp/fritap_ios.log -k keys.log com.example.app

Do not reach for --pcap, -f, --timeout or --offsets on iOS as a matter of course. Each has an iOS-specific caveat documented above.

3. Data management¶

mkdir ios_analysis_$(date +%Y%m%d)
cd ios_analysis_$(date +%Y%m%d)

fritap -m -k app_keys.log -j app_metadata.json com.example.app

4. Documentation¶

# Host-side versions
frida --version > device_info.txt

# Device-side OS version — this exact value is what the offset code reads
ssh root@<device-ip> 'sysctl -n kern.osproductversion' >> device_info.txt

# App inventory
frida-ps -Uai > app_info.txt

Common iOS App Categories¶

Social media apps¶

fritap -m -k instagram_keys.log com.burbn.instagram
fritap -m -k twitter_keys.log com.atebits.Tweetie2
fritap -m -k tiktok_keys.log com.zhiliaoapp.musically

Communication apps¶

fritap -m -k whatsapp_keys.log net.whatsapp.WhatsApp
fritap -m -k signal_keys.log org.whispersystems.signal
fritap -m -k telegram_keys.log ph.telegra.Telegraph

Financial apps¶

# Use test accounts only
fritap -m -k banking_keys.log com.example.bank
fritap -m -k paypal_keys.log com.paypal.ppmobile

Browsers and Chromium-based apps¶

# Chrome for iOS bundles Cronet — registered but untested on iOS,
# and a known --modern regression, so stay on the default path
fritap -m -k chrome_keys.log com.google.chrome.ios

Flutter apps¶

# Pattern-based, arm64 only
fritap -m -k flutter_keys.log com.example.flutterapp

Next Steps¶

• Android Analysis: Check the Android Platform Guide
• Desktop Analysis: See the Linux, macOS and Windows guides
• Advanced Features: Learn about Pattern-based Hooking
• Troubleshooting: Review Common Issues