Certificate Pinning: Benefits and Limitations

TLS already authenticates your server through trusted certificate authorities (CAs). Pinning adds a stricter rule: even a valid certificate from a trusted CA is rejected unless its public key matches one you've pinned. That protects against mis-issued certificates and some interception setups, at the cost of operational risk.

What pinning does and doesn't protect

Android apps targeting API 24+ already ignore user-installed CAs by default, which blocks many casual interception setups. Pinning additionally defends against mis-issued certificates from trusted CAs. It does not stop an attacker who controls the device and modifies your app.

Pinning with Network Security Config

<network-security-config>
    <domain-config>
        <domain includeSubdomains="true">api.example.com</domain>
        <!-- Expiration: after this date pinning is NOT enforced, so old app versions keep working -->
        <pin-set expiration="2027-06-30">
            <!-- SHA-256 of the SubjectPublicKeyInfo: current key + at least one backup -->
            <pin digest="SHA-256">AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=</pin>
            <pin digest="SHA-256">BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=</pin>
        </pin-set>
    </domain-config>
</network-security-config>

The pin values above are placeholders. Compute real ones from your keys.

Pinning with OkHttp

val pinner = CertificatePinner.Builder()
    .add("api.example.com", "sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=")   // current
    .add("api.example.com", "sha256/BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=")   // backup
    .build()

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

Prefer Network Security Config when possible: it's declarative, applies app-wide, and supports an expiration date.

Pinning safely

1. Pin public keys, not certificates, and preferably an intermediate CA or your own key that you control across renewals.
2. Always include backup pins: a second key you hold offline, or another CA you might move to.
3. Set an expiration date so very old app versions don't break permanently.
4. Coordinate with whoever manages certificates, such as the backend team or CDN, and document the rotation process.
5. Monitor pinning failures and have a plan, such as a forced update, if something goes wrong.

Should you pin?

For many apps, correct TLS, the default distrust of user CAs, server-side validation and Play Integrity provide better risk reduction per unit of operational effort.

Testing

• Verify the pin values match the production chain before release, using a staging environment that mirrors production certificates.
• Test that a deliberately wrong pin fails closed, and that debug overrides work for development proxies.

Frequently asked questions

Conclusion

Certificate pinning adds protection against mis-issued or unexpected certificates, but brings real outage risk. If you pin, pin public keys with backups and an expiration, coordinate rotations, and monitor. Otherwise, rely on solid TLS defaults and server-side controls.

Next step: protect data at rest with Encrypted Data Storage in Android.