Certificate pinning

On this page 7

Certificate pinning is a client-side security technique in which an application accepts only a specific certificate or public key for a given host, instead of trusting any certificate that chains to a recognized certificate authority. In the Internet trust model, it narrows the set of acceptable identities so that a misissued or fraudulently obtained certificate cannot be used to impersonate the server.

Pinning is a deliberate departure from the default Web PKI, where hundreds of authorities can vouch for any domain. It offers strong protection against interception, but it also creates an operational dependency that can lock legitimate users out when keys change without planning.

How certificate pinning works

Certificate pinning works by adding a second, stricter check after normal certificate validation. During the TLS handshake, the client first verifies the certificate chain, the validity dates and the host name as usual. It then compares an element of the presented chain with a stored pin, a value that was embedded in the application or recorded on an earlier connection.

The most common pin is a SHA-256 hash of the SubjectPublicKeyInfo (SPKI) field of an X.509 certificate. Hashing the public key rather than the whole certificate means the pin survives certificate renewal with the same key pair, because renewed certificates change serial numbers and dates but keep the key. If no certificate in the chain matches any stored pin, the client aborts the connection, even when the chain is otherwise valid.

The table below shows the main elements a client can pin and how each choice behaves when certificates change.

Pinned elementWhat is comparedSurvives renewalMain risk
Leaf certificateFull certificate hashNoBreaks at every renewal
Leaf public keySPKI hash of the server keyYes, if key is reusedBreaks on key rotation
Intermediate CA keySPKI hash of the issuing CAYesBreaks if the CA changes intermediates
Root CA keySPKI hash of the trust anchorYesWeakest protection, widest scope
Elements that can be pinned

Static and dynamic pinning models

Pinning is delivered either statically, with pins compiled into the client, or dynamically, with pins learned from the server at run time. Static pinning is typical of mobile applications and of browsers that ship preloaded pin lists for high-value domains. The developer controls both ends of the connection, so the pin set can be updated together with the app.

Dynamic pinning was standardized as HTTP Public Key Pinning (HPKP) in RFC 7469. A server sent a Public-Key-Pins header listing hashes and a lifetime, and the browser enforced them on later visits. HPKP was deprecated and removed from major browsers around 2018 because a single wrong header could make a site unreachable for months, and attackers who briefly controlled a server could set hostile pins.

The following comparison summarizes how the main delivery models differ in control and failure behavior.

ModelWhere pins liveUpdate pathCurrent status
Static app pinningApplication code or configurationNew app releaseWidely used in mobile apps
Browser preload pinsBrowser source codeBrowser updateLimited to a few domains
HPKP headerBrowser cache per hostServer response headerDeprecated and removed
Trust-on-first-useClient store after first contactManual resetCommon in SSH, rare in HTTPS
Pinning delivery models compared

Certificate pinning addresses the too-many-authorities problem, while neighboring controls address different gaps in Internet trust. HSTS forces HTTPS but still accepts any valid certificate. Certificate transparency does not block a bad certificate; it makes misissuance publicly detectable through append-only logs. Revocation through OCSP or a certificate revocation list withdraws trust after a problem is known.

Mutual TLS is sometimes confused with pinning, but it authenticates the client to the server, the opposite direction. A private PKI with a dedicated root, used only by one application, achieves a similar effect to pinning by design, because no public authority is trusted at all.

ControlPrimary threat addressedBlocks a misissued certificateOperational risk
Certificate pinningRogue or compromised CAYes, at the clientHigh lockout risk
HSTSProtocol downgrade to HTTPNoLow to moderate
Certificate transparencyUndetected misissuanceNo, detects itLow
CAA recordsIssuance by unauthorized CAsPartly, at issuanceLow
Mutual TLSUnauthenticated clientsNoModerate
Related controls and the threat each addresses

Implementing certificate pinning safely

Safe pinning depends on always having a backup pin that is not currently in use. A sound pin set contains the hash of the active key plus at least one backup key generated in advance and stored offline, so the operator can rotate keys without stranding clients. Many teams also pin an intermediate or root key of two different authorities, accepting weaker protection in exchange for resilience.

Platform features reduce custom code. Android supports pins in its Network Security Configuration with an expiration date, and iOS offers pinned keys through App Transport Security settings. Libraries such as OkHttp provide a CertificatePinner class. An expiration date on the pin set is a valuable safety valve: after it passes, the client falls back to ordinary validation instead of failing permanently.

The decision table below matches common situations with a reasonable pinning strategy.

SituationRecommended approachReason
Banking or payment appPin leaf keys plus offline backupHigh-value target, controlled release cycle
App calling third-party APIsAvoid pinning or pin the provider’s CAProvider may rotate keys without notice
Public websiteDo not pin; use HSTS and CAABrowsers no longer support HPKP
Internal service meshPrivate PKI instead of pinsFull control of the trust anchor
IoT device with long lifetimePin multiple CA keys with updatesFirmware may outlive any single key
Choosing a pinning strategy

Limitations and common mistakes

The defining weakness of certificate pinning is that availability depends on key management discipline. An outage occurs when a certificate is replaced by a new key or a new authority that the shipped pin set does not include, and users of older app versions may stay broken until they update.

  • Pinning only one key leaves no recovery path when that key is lost or compromised.
  • Pinning a CDN or cloud provider certificate fails when the provider rotates certificates on its own schedule.
  • Ignoring corporate inspection proxies makes the app fail on managed networks, which may be acceptable but must be a conscious choice.
  • Treating pinning as a defense against a compromised device is a misconception, because tools such as instrumentation frameworks can bypass checks on a rooted phone.
  • Shipping pins without monitoring or reporting hides failures until users complain.

In everyday language

Normally, a browser or app trusts a website if any one of many recognized authorities has vouched for it. That works like a building that accepts an ID card from any of hundreds of offices. Certificate pinning narrows that list: the app remembers exactly which key the real server uses and refuses anything else.

The benefit is that a forged but official-looking certificate is rejected. The cost is that the owner must plan key changes carefully, because a forgotten backup key can lock everyone out until the app is updated.

Seen in the real world

A regional bank releases a mobile app that talks to a single API host. The security team pins two SPKI hashes: the key behind the current certificate and a backup key kept in a hardware security module that has never been deployed. The pin set has a twelve-month expiration, and every release refreshes it.

Months later, a customer connects through a public Wi-Fi network where an attacker presents a certificate issued by a compromised authority. Ordinary validation would accept it, but the app finds no matching pin and refuses to send credentials. When the bank later rotates its server key, it switches to the prepared backup key, so no customer loses access during the change.