fritap support on iOS 16.x

[eyJhb]

I'm trying to run fritap on iOS 16.x on a jalbroken iPhone (palerain), but I just get a constant rain of crashes before anything even starts. I can run this script https://github.com/jankais3r/Frida-iOS-15-TLS-Keylogger/blob/main/ios-tls-keylogger.js (with the updated offset) just fine, but when I use fritap, it just seems to crash.

I'm not sure the best way to debug this is. I've tried to comment out everything in agent/platforms/ios.ts related to hooking, to ensure it wasn't that, but it still crashes.

diff --git a/agent/platforms/ios.ts b/agent/platforms/ios.ts
index 64b9a2b..107ee93 100644
--- a/agent/platforms/ios.ts
+++ b/agent/platforms/ios.ts
@@ -24,19 +24,19 @@ function hook_iOS_SSL_Libs(hookRegistry: HookRegistry, is_base_hook: boolean) {
 
 
 export function load_ios_hooking_agent() {
-    hookRegistry.registerAll([
-        // TLS libraries (TLS protocol family)
-        { platform: plattform_name, pattern: /.*libboringssl\.dylib/, hookFn: (use_modern ? boring_execute_modern : boring_execute), library: "BoringSSL", libraryType: "boringssl", protocol: "tls" },
-        { platform: plattform_name, pattern: /.*cronet.*\.dylib/, hookFn: (use_modern ? cronet_execute_modern : cronet_execute), library: "Cronet", libraryType: "boringssl", protocol: "tls" },
-        { platform: plattform_name, pattern: /.*flutter.*\.dylib/, hookFn: (use_modern ? flutter_execute_modern : flutter_execute), library: "Flutter BoringSSL", libraryType: "boringssl", protocol: "tls" },
-    ]);
-
-    hook_iOS_SSL_Libs(hookRegistry, true);
-    processScanResults(scan_results, plattform_name, true, selected_protocol);
-    hookDynamicLoader({
-        platform: plattform_name,
-        platformLabel: "iOS",
-        loaderLibrary: /libSystem.B.dylib/,
-        functionName: "dlopen",
-    }, hookRegistry, moduleNames, false, selected_protocol);
-}
\ No newline at end of file
+    // hookRegistry.registerAll([
+    //     TLS libraries (TLS protocol family)
+    //     { platform: plattform_name, pattern: /.*libboringssl\.dylib/, hookFn: (use_modern ? boring_execute_modern : boring_execute), library: "BoringSSL", libraryType: "boringssl", protocol: "tls" },
+    //     { platform: plattform_name, pattern: /.*cronet.*\.dylib/, hookFn: (use_modern ? cronet_execute_modern : cronet_execute), library: "Cronet", libraryType: "boringssl", protocol: "tls" },
+    //     { platform: plattform_name, pattern: /.*flutter.*\.dylib/, hookFn: (use_modern ? flutter_execute_modern : flutter_execute), library: "Flutter BoringSSL", libraryType: "boringssl", protocol: "tls" },
+    // ]);
+
+    // hook_iOS_SSL_Libs(hookRegistry, true);
+    // processScanResults(scan_results, plattform_name, true, selected_protocol);
+    // hookDynamicLoader({
+    //     platform: plattform_name,
+    //     platformLabel: "iOS",
+    //     loaderLibrary: /libSystem.B.dylib/,
+    //     functionName: "dlopen",
+    // }, hookRegistry, moduleNames, false, selected_protocol);
+}

Any tips/tricks for how I can best debug this issue? fritap is becoming quite large, so the entrypoint feels more difficult to find :)

[monkeywave]

Hi @eyJhb

thanks for posting this, and apologies for the late reply. We only recently came across your post here in Discussions.

I took a closer look at the Apple/iOS path, and your observation that the standalone keylogger works with the updated offset while friTap crashes was a very useful clue.

The short version is: the offsets you contributed were not the problem. The bug was in how friTap selected and applied them.

What caused the crash

On Apple's BoringSSL, SSL_CTX_set_keylog_callback is not exported. friTap therefore hooks the exported SSL_CTX_set_info_callback, obtains the live SSL_CTX, and writes its own keylog callback directly into the structure at the expected byte offset.

That makes getting the offset right quite important: if friTap selects the wrong one, it writes into a neighbouring SSL_CTX field instead, which can immediately crash the target.

The old implementation selected that offset through a kCFCoreFoundationVersionNumber-based version ladder. The values contributed for the individual releases were fine, but the lookup logic around them was not. In particular, the final branches acted as open-ended catch-alls, so newer releases could continue receiving an offset that belonged to an older SSL_CTX layout.

There was also an error in the CF-version-to-iOS-version mapping that could put iOS 16 into the wrong version bucket.

So your original offsets were useful and correct for the versions they were determined on; friTap's surrounding version-selection logic was the part that failed.

What changed

I have changed the Apple path so that friTap no longer relies primarily on a version table.

Instead, it now tries to derive the offset directly from the libboringssl.dylib loaded by the target. Frida's Module.enumerateSymbols() can expose the non-exported SSL_CTX_set_keylog_callback, whose ARM64 implementation is essentially:

str x1, [x0, #imm]
ret

The immediate value is the SSL_CTX::keylog_callback offset, so friTap can obtain the value from the actual binary being instrumented rather than assuming it from the OS version.

The version table remains as a fallback for cases where the symbol cannot be recovered.

I also found a separate Apple spawn-mode issue: friTap queried NSProcessInfo while the spawned process was still suspended. That can kill the target before any TLS hook is installed. Version detection now uses sysctl first instead.

A few diagnostics have been added around this as well:

• --probe loads the agent and reports the selected platform path without installing TLS hooks.
• --script-load-timeout prevents script.load() from waiting indefinitely.
• iOS crash reports are now collected and decoded for both spawn and attach mode.
• Debug output now reports the selected offset and whether it came from the target binary or the fallback table.

Finding your way through friTap

Your comment about the entrypoint is fair — the project has grown quite a bit.

The easiest way to think about it is as two entrypoints and one platform switchboard.

On the host side:

fritap
  → friTap/friTap.py::main
  → cli()
  → SessionManager.start_session()
  → SSL_Logger.instrument()

SSL_Logger.instrument() is where the Frida agent is created and loaded.

On the agent side, agent/fritap_agent.ts detects the platform and eventually calls the corresponding platform loader.

For iOS, the main switchboard is:

agent/platforms/ios.ts

That file maps module-name patterns to the corresponding hook implementation. For libboringssl.dylib, the legacy path currently looks roughly like this:

agent/platforms/ios.ts
  → boring_execute()
  → installKeylogCallbackViaCtxWrite()
  → resolveKeylogCallbackOffset()
  → SSL_CTX + offset

One potentially confusing detail is that use_modern currently defaults to false, so agent/legacy/ is the code path that runs unless you explicitly use --modern.

That may also explain why commenting things out in one part of the agent did not necessarily have the effect you expected.

One other development gotcha: agent/**/*.ts is the source, but friTap/fritap_agent.js is the compiled bundle that friTap actually loads. After changing the TypeScript, rebuild it with:

npm ci --ignore-scripts
./dev/compile_agent.sh

Otherwise it is very easy to think a change had no effect while still running the previous agent bundle.

If you still have the iOS 16 device

If you are able to test this again, the most useful first step would be:

fritap -do ...

The debug output should now show the detected iOS version, selected SSL_CTX offset, and whether that offset was derived from the loaded binary or came from the fallback table.

I would also try:

fritap --probe ...

first. If the application survives --probe but crashes during the normal run, we know the failure happens during hook installation rather than during agent startup.

As an additional test, --modern avoids this particular SSL_CTX field write and hooks bssl::ssl_log_secret instead. If the application survives with --modern, that would be another strong indication that the old struct-write path was responsible.

One caveat: iOS support is still not as broad as the other platforms. Apple's system libboringssl.dylib is covered, but several TLS libraries that friTap supports on macOS/Linux/Windows are not yet registered on the iOS path, and QUIC/SSH coverage is still missing there as well.

Thanks again for posting this :-) — and also for the earlier offset contribution. Digging into this made it clear that the values themselves were not the issue.

All the best

Daniel