How to implement certificate pinning on Android without breaking updates

The right approach: pin the key, not the certificate

Pinning the server certificate forces a new app release on every renewal. Pinning the SPKI, that is the hash of the public key, lets you renew the certificate as often as you like as long as you keep the same key pair.

On Android, the supported way to do this is Network Security Configuration: a declarative XML file with the pins per domain, rather than a hand-written TrustManager. Being declarative, it is far harder to get wrong in a way that silently disables the check.

The backup pin is not optional

A single pin is a single point of failure. If that key is compromised and has to be replaced urgently, every version shipped with only that pin is dead until the user updates, and users cannot be made to update.

The correct practice is to generate a second key pair in advance, keep it offline, and ship its pin alongside the one in use. On rotation day the apps already trust the new key before a certificate for it exists.

The expiration date is a trap

Network Security Configuration accepts an expiration attribute on the pin set. Past that date the check is disabled and the app falls back to default behaviour.

It is a reasonable safeguard against stranding old versions, but be clear about what it means: an old app eventually stops being pinned at all. If that app is not expected to live that long, force an update before the date arrives.

What to check before shipping

• That there are at least two pins: the key in use and the backup.
• That the backup matches a key pair that genuinely exists and is held safely, not a placeholder.
• That pinning has been tested with an interception proxy and the connection fails as it should.
• That there is a written rotation procedure, naming who runs it and in what order.
• That you know how many active installs each version has, so you can size the impact of an emergency rotation.

What pinning does not give you

Pinning guarantees you are talking to your server, not that your server is talking to your app. An attacker who reimplements the client connects without trouble: they are not intercepting anything, they are simply a new client. Authenticating the client is a different problem, and mTLS is what solves it.