What is certificate pinning? How it works and why it breaks

Certificate pinning is a technique in which an app accepts only a specific certificate or public key for a server, instead of any certificate a trusted authority has issued for that name. It protects against a wrongly issued certificate being used to intercept traffic. It also makes the app fail whenever the server's certificate changes in a way the pin did not anticipate, which, with certificates now replaced every few months, is its main practical problem. It is part of the glossary.

Quick facts

Used in

mobile and desktop apps, API clients, devices

Not used in

browsers for ordinary websites; the browser mechanism, HPKP, was removed

What is pinned

the certificate, its public key, or an issuing authority's key

Main risk

the app stops connecting after the server's certificate is replaced

Platform support

Android Network Security Config; NSPinnedDomains on Apple platforms

How certificate pinning works

Normally a client accepts a server's certificate if it chains to a root in the client's trust store and covers the hostname. Any of the many trusted authorities could issue such a certificate. See certificate chains.

Pinning adds one more check. The app carries a fingerprint, the pin, of a key or certificate it expects. After the normal checks pass, the app compares what the server presented with the pin. If nothing in the chain matches, the app refuses the connection, even though the certificate is otherwise valid.

The pin is fixed when the app is built or configured. Changing it requires an app update or a configuration change on every installed copy. SSH clients keep a similar record by default: they store a server's host key in known_hosts on first connection and warn if it ever changes, as described in the comparison of SSL and SSH.

What can be pinned

Pinning the public key rather than the certificate is the usual recommendation, because a certificate can be renewed with the same key. The pin is a hash of the key's SubjectPublicKeyInfo, usually SHA-256 in base64; SubjectPublicKeyInfo is the field of an X.509 certificate that holds the public key and its algorithm.

Why pinning breaks

The trouble with pinning is operational. A pin records what the server presents today, and the server's certificate changes on someone else's schedule. The protocol version plays no part in this: a certificate carries none, which is why an SSL certificate and a TLS certificate are the same thing; see how SSL and TLS differ.

• Certificates are replaced more often. The CA/Browser Forum ballot SC-081v3 lowers the maximum lifetime of public certificates to 200 days from March 2026, 100 days from March 2027 and 47 days from March 2029. A certificate pin then breaks several times a year. See renewal.

• Keys and intermediates change too. Automated clients often generate a new key at each renewal. Authorities rotate their intermediates, and some issue from several intermediates at once, so two consecutive certificates for the same site can chain through different ones.

• The app cannot be fixed quickly. When a pin breaks, every installed copy of the app fails until users install an update. Users who do not update stay broken.

That is why pinning to the leaf certificate is now rarely defensible for public services, and why pins should always come with a backup.

Pinning in browsers: HPKP

Browsers once let websites set pins with an HTTP header, HTTP Public Key Pinning, defined in RFC 7469. A wrong pin could lock visitors out of a site for as long as the header said, and an attacker who briefly controlled a site could pin it to keys the owner did not have. Browsers removed HPKP. Certificate Transparency took over its purpose: wrongly issued certificates are found in public logs instead of being blocked by pins.

Websites today have no pinning mechanism in browsers, and none is needed. The HSTS security header, a different mechanism, still tells browsers to reach a site only over HTTPS, but it has never restricted which certificates they accept.

If you pin in an app

When an app talks to an API you control and the threat justifies it, pinning can be done with less risk:

• Pin keys, not certificates, and pin at least two: the current key and a backup key kept offline, or keys of two authorities you could switch to.

• Use the platform's configuration rather than custom code. Android's Network Security Config supports a pin set with an expiry date, after which pinning stops instead of breaking the app. Apple platforms provide NSPinnedDomains in the app's settings.

• Plan rotation before release. Write down who changes the server's key or authority, and how the app learns the new pin before the old one is retired.

• Keep a way out. An expiry date on the pins, or a remotely updated pin list, prevents a permanent outage for users who never update.

The OWASP Pinning Cheat Sheet covers the implementation details per platform.

For most apps, the alternative is better: rely on the platform's trust store, require Certificate Transparency, and keep the server's certificate valid. Pinning protects against a rare threat by adding a common failure.

Pinning and interception tools

Corporate proxies and debugging tools read encrypted traffic by presenting their own certificate, issued by a root installed on the device. An app with pins refuses those connections, which is why some apps fail on networks that inspect traffic. That is pinning working as designed. The same mechanism explains failures behind unable to get local issuer certificate in tools that do not pin but do not trust the proxy's root.

FAQ