🔐 SSL Pinning in Mobile Apps: Android & iOS (Practical Guide + Trade-offs) - Part 1

When building mobile apps that consume APIs over the internet, HTTPS is mandatory—but sometimes it’s not enough.

If your app handles sensitive data (finance, health, enterprise), you might want to go one step further:

👉 Certificate Pinning (aka “SSL pinning”)

This article explains:

• What SSL pinning actually is (and what it isn’t)

• How to implement it in Android

In a second part, these topics will be covered:

• How to implement it in iOS (both .cer and Public Key approaches)

• The real trade-offs nobody tells you

🧠 What is SSL Pinning (really)?

Despite the name, modern apps use TLS, not SSL.

👉 The correct term is:

• Certificate Pinning

• or TLS Pinning

But “SSL pinning” is still widely used.

🔐 Default HTTPS behavior

By default, your app trusts any valid certificate signed by trusted Certificate Authorities (CAs).

That means:
App → HTTPS → Server (valid cert) → OK

🚨 The problem

If an attacker installs a malicious certificate (e.g. on public WiFi), they could:

• Intercept traffic
• Decrypt requests
• Act as a proxy (MITM attack)

🔐 What Pinning Changes

Instead of trusting all valid certs:

👉 Your app trusts only a specific certificate or public key

If it doesn’t match → ❌ connection rejected

In Android, SSL pinning can be implemented either at the HTTP client level (e.g., OkHttp) or at the platform level using Network Security Config.

📱 Android Implementation (OkHttp)

Android makes this relatively straightforward thanks to OkHttp.

✔️ Public Key Pinning (recommended)

val certificatePinner = CertificatePinner.Builder()
    .add("api.yourservice.com", "sha256/AAAAAAAAAAAAAAAAAAAA...")
    .build()

val client = OkHttpClient.Builder()
    .certificatePinner(certificatePinner)
    .build()

🧪 How to get the SHA-256 hash

You can extract it using OpenSSL:

openssl s_client -connect api.yourservice.com:443 -servername api.yourservice.com \
  | openssl x509 -pubkey -noout \
  | openssl pkey -pubin -outform der \
  | openssl dgst -sha256 -binary \
  | openssl enc -base64

🧭 Alternative on Android: Network Security Config (Platform-Level Pinning)

So far, we’ve implemented SSL pinning using OkHttp, which gives us fine-grained control at the HTTP client level.

However, Android also provides a platform-level approach: Network Security Config.

Instead of configuring pinning in code, you can declare it in XML and apply it globally to your app.

🔧 Example Configuration

Create a file under:

res/xml/network_security_config.xml

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config cleartextTrafficPermitted="false">
        <domain includeSubdomains="true">api.yourservice.com</domain>

        <pin-set expiration="2026-05-09">
            <pin digest="SHA-256">YOUR_BASE64_SHA256_PIN</pin>
        </pin-set>
    </domain-config>
</network-security-config>

Then reference it in your AndroidManifest.xml:

<application
    android:networkSecurityConfig="@xml/network_security_config"
    ... >

🧠 How It Works

This configuration tells Android:

Only trust connections to this domain if the server’s certificate matches the pinned public key.

Unlike OkHttp’s CertificatePinner, this operates at the platform level, not just within a specific HTTP client.

⚖️ OkHttp vs Network Security Config

⚠️ Trade-offs

• Still subject to certificate rotation issues
• Less dynamic than code-based approaches
• Android-only (no equivalent in iOS)

🧭 When Should You Use It?

Use Network Security Config when:

• You want a centralized security policy
• Your app uses multiple networking libraries
• You prefer a declarative approach

Use OkHttp pinning when:

• You need fine-grained control
• You want to scope pinning to specific requests or clients

🧠 Key Insight

Both approaches ultimately solve the same problem:

Restricting trust to a known certificate or public key.

The difference lies in where the responsibility lives:

• In your networking layer (OkHttp)
• Or in the Android platform configuration

Wrapping Up (Part 1)

At this point, we’ve covered what SSL pinning really is, what problems it solves (and what it doesn’t), and how to implement it on Android using a modern, production-ready approach.

If there’s one takeaway from this first part, it’s this:

Pinning is not about replacing your security model — it’s about strengthening the transport layer.

On Android, the ecosystem makes it relatively straightforward to adopt public key pinning with tools like OkHttp. However, the real challenge isn’t implementation — it’s operational discipline:

• Handling certificate rotation
• Avoiding hard failures in production
• Understanding when pinning actually adds value

Before moving forward, ask yourself:

Do I really need pinning, or am I trying to compensate for missing backend security?

In the next part, we’ll move to iOS — where things are a bit more low-level, and where the trade-offs become even more evident.