Introduction to SSL Pinning and OkHttp3

SSL (Secure Sockets Layer) pinning, more accurately TLS (Transport Layer Security) pinning, is a security mechanism designed to prevent Man-in-the-Middle (MitM) attacks by ensuring that an application only trusts a specific, pre-defined server certificate or public key. Instead of relying solely on the device’s default trust store, the application ‘pins’ the expected certificate or public key. If the server presents a certificate that doesn’t match the pinned one, the connection is aborted, even if the certificate is otherwise valid and signed by a trusted CA.

OkHttp3 is a widely used, high-performance HTTP client for Java and Android. Its popularity means many Android applications leverage its robust networking features, including its built-in SSL pinning capabilities via the CertificatePinner class. Bypassing SSL pinning in OkHttp3 applications is a common challenge for penetration testers and security researchers attempting to intercept and analyze network traffic using tools like Burp Suite or OWASP ZAP.

Prerequisites for Bypassing SSL Pinning

Before diving into the bypass, ensure you have the following setup:

• Rooted Android Device or Emulator: Frida requires root privileges to inject into target processes.
• ADB (Android Debug Bridge): For interacting with your Android device/emulator.
• Frida-server: The Frida agent running on the Android device. Download the correct architecture (e.g., frida-server-16.x.x-android-arm64) from the Frida GitHub releases.
• Frida-tools: The command-line client on your host machine (pip install frida-tools).
• Proxy Tool: Such as Burp Suite or OWASP ZAP, configured to listen on your host machine and with its CA certificate installed on your Android device/emulator.

Setting Up Frida on Android

1. Push Frida-server to device:

   adb push /path/to/frida-server /data/local/tmp/

2. Grant execute permissions:

   adb shell "chmod 755 /data/local/tmp/frida-server"

3. Run Frida-server (in a new shell):

   adb shell "/data/local/tmp/frida-server &"

   Verify it’s running with adb logcat | grep frida or frida-ps -U on your host.

The Frida SSL Pinning Bypass Script for OkHttp3

This comprehensive Frida script targets common pinning implementations in OkHttp3 by hooking critical methods. It primarily focuses on neutralizing okhttp3.CertificatePinner.check and also provides a fallback for generic X509TrustManager bypasses, which can catch other forms of pinning or trust issues.

Java.perform(function () { try { var CertificatePinner = Java.use('okhttp3.CertificatePinner'); CertificatePinner.check.overload('java.lang.String', 'java.util.List').implementation = function (hostname, certificates) { console.log('Bypassing OkHttp3 CertificatePinner.check for: ' + hostname); return; // Do nothing, effectively bypassing the pinning }; console.log('OkHttp3 CertificatePinner.check hook installed successfully!'); } catch (e) { console.log('OkHttp3 CertificatePinner.check hook failed to install: ' + e.message); } try { // Generic X509TrustManager bypass for other pinning methods var X509TrustManager = Java.use('javax.net.ssl.X509TrustManager'); var TrustManagerFactory = Java.use('javax.net.ssl.TrustManagerFactory'); var SSLContext = Java.use('javax.net.ssl.SSLContext'); // Hook TrustManagerFactory to return our custom trust manager TrustManagerFactory.getTrustManagers.implementation = function () { var trustManagers = this.getTrustManagers(); for (var i = 0; i < trustManagers.length; i++) { try { var tm = Java.cast(trustManagers[i], X509TrustManager); tm.checkServerTrusted.overload('[Ljava.security.cert.X509Certificate;', 'java.lang.String').implementation = function (chain, authType) { console.log('Bypassing checkServerTrusted for ' + authType); }; console.log('Hooked X509TrustManager checkServerTrusted!'); } catch (e) { console.log('Failed to hook X509TrustManager checkServerTrusted: ' + e.message); } } return trustManagers; }; // Hook SSLContext.init to use our custom trust manager SSLContext.init.overload('[Ljavax.net.ssl.KeyManager;', '[Ljavax.net.ssl.TrustManager;', 'java.security.SecureRandom').implementation = function (keyManagers, trustManagers, secureRandom) { console.log('Bypassing SSLContext.init...'); var TrustManagerArray = Java.array('javax.net.ssl.TrustManager', [Java.cast(Java.use('android.net.http.X509TrustManagerExtensions').$new(), X509TrustManager)]); // Create a dummy TrustManager that trusts everything. var BypassTrustManager = Java.registerClass({ name: 'com.android.net.ssl.BypassTrustManager', implements: [X509TrustManager], methods: { checkClientTrusted: function (chain, authType) {}, checkServerTrusted: function (chain, authType) {}, getAcceptedIssuers: function () { return []; } } }); this.init(keyManagers, [BypassTrustManager.$new()], secureRandom); console.log('SSLContext.init hook installed with BypassTrustManager!'); }; } catch (e) { console.log('Generic X509TrustManager and SSLContext hooks failed: ' + e.message); } console.log('Frida SSL Pinning Bypass script loaded!');});

How the Script Works

1. okhttp3.CertificatePinner.check Hook: This is the primary target for OkHttp3 specific pinning. We use .overload('java.lang.String', 'java.util.List').implementation to intercept the check method. By making its implementation do nothing (return;), we effectively tell the application that the certificate is always valid according to its pinning rules.
2. Generic X509TrustManager Hook: Many Android apps use X509TrustManager directly or indirectly for trust decisions. This part of the script attempts to:
   • Hook TrustManagerFactory.getTrustManagers(): It iterates through existing trust managers and hooks their checkServerTrusted method to do nothing.
   • Hook SSLContext.init(): This is a powerful hook. When an SSLContext is initialized (which happens when an app sets up its TLS configuration), we replace the app’s potentially strict TrustManager array with our own custom BypassTrustManager. This custom trust manager implements X509TrustManager but its checkClientTrusted, checkServerTrusted, and getAcceptedIssuers methods are empty, effectively trusting all certificates.

Executing the Bypass and Intercepting Traffic

1. Save the script: Save the Frida script above as, for example, okhttp3_bypass.js.
2. Identify the target app’s package name:

   adb shell pm list packages | grep <app_name>

   (e.g., com.example.myapp)

3. Run Frida with the script:

   frida -U -f com.example.myapp -l okhttp3_bypass.js --no-pause

   -U specifies a USB device. -f <package_name> spawns and attaches to the application. -l <script.js> loads our bypass script. --no-pause starts the application immediately without waiting for user input.

4. Configure Proxy: Ensure your Android device’s Wi-Fi settings are configured to use your host machine’s IP address and the port your proxy tool (e.g., Burp Suite) is listening on.
5. Observe Traffic: Launch the target application on your Android device. You should now see its network traffic flowing through your proxy tool, indicating a successful SSL pinning bypass.

Troubleshooting Common Issues

• Frida not attaching: Ensure frida-server is running on the device, and you have the correct package name. Check adb logcat for any Frida-related errors.
• Script errors: Carefully review the Frida script for syntax errors. Check the console output in your Frida session for JavaScript exceptions.
• Still encountering pinning errors:
  • The app might be using a different networking library or a custom implementation not covered by the generic hooks.
  • The app might be performing certificate validation at a lower level or using native code (JNI).
  • Ensure your proxy’s CA certificate is correctly installed and trusted on the Android device.

Conclusion

Bypassing SSL pinning in Android applications, especially those using robust libraries like OkHttp3, requires a targeted approach. This guide provides a powerful Frida script that neutralizes OkHttp3’s CertificatePinner and offers a comprehensive X509TrustManager and SSLContext hooking strategy to handle various pinning scenarios. With this knowledge and the right tools, security researchers can effectively intercept and analyze application traffic, uncovering potential vulnerabilities that would otherwise remain hidden.