TLS certificate pinning can strengthen certificate verification for a controlled mobile app or API client, but an incorrect pin can also block every legitimate connection. This guide explains when pinning is appropriate, how certificate and public-key pins differ, how to plan rotation with backup pins, and how to recover safely if a deployment causes a lockout.
Overview
TLS already verifies a server through the public certificate authority system. During a normal connection, the client checks the server certificate, hostname, validity period, signature chain, and other certificate constraints before trusting the connection. Certificate pinning adds an application-specific rule: the client must also recognize a particular certificate or public key.
Pinning is most useful when the organization controls both the client and the service it contacts, such as a mobile application connecting to a known API. It is less suitable for general-purpose websites, browser users, or services whose certificates and keys are managed by several independent teams. A pin that is too strict, poorly distributed, or impossible to update can turn an ordinary certificate renewal into a service outage.
Certificate pinning versus public-key pinning
Certificate pinning associates the client with a specific certificate, often identified by a cryptographic digest. When that certificate expires or is replaced, the application may reject the new certificate even if the replacement is valid and issued for the correct domain.
Public-key pinning associates the client with the public key, or a digest of the key, rather than one certificate. This can allow a certificate to be renewed while the same key remains in use. It does not remove the need for careful key management: if the key is compromised or intentionally rotated, the application must receive a new trusted pin before the change.
Pinning is an additional control, not a replacement for ordinary TLS validation. The client should continue to validate the hostname, certificate dates, trust chain, key usage, and relevant platform security rules. A successful pin match alone should not make an otherwise invalid certificate acceptable.
Decision table
| Scenario | Default approach | Why |
|---|---|---|
| Public website used through standard browsers | Do not add application pinning | Certificate authority validation and normal TLS controls are generally the appropriate model. |
| Mobile app controlled by your organization and calling your API | Consider app-level public-key pinning | The client and endpoint are known, so the additional trust rule can be managed deliberately. |
| Client connects to customer-selected or third-party domains | Avoid fixed pins unless each deployment can manage its own configuration | The certificate and key lifecycle may be outside your control. |
| Internal service-to-service traffic | Evaluate pinning alongside managed trust stores, mutual TLS, and service identity controls | Operational automation and key rotation may provide better control than hard-coded pins. |
| Legacy client that cannot be updated quickly | Use caution and document an emergency path | Any pin change can become a lockout if the client has no reliable update mechanism. |
Checklist by scenario
For a mobile application
- Define the exact endpoints. List every hostname, environment, region, and failover endpoint the app may contact. Do not assume that a staging certificate or alternate API hostname will match the production pin.
- Choose the pin target. Decide whether the app will pin a leaf certificate, an intermediate certificate, or a public key. A public-key strategy can reduce unnecessary changes during routine certificate renewal, but it still requires a controlled key lifecycle.
- Add at least one planned backup. A backup pin should represent a separately managed, valid future path. Store it securely and test that the app can use it before the primary path is changed.
- Keep ordinary TLS checks enabled. Pinning should be an additional condition after normal certificate and hostname validation, not a shortcut around them.
- Test real release behavior. Test fresh installation, upgrade from an older version, offline startup, captive or altered networks, certificate renewal, server failover, and the case where the pin does not match.
- Confirm the update path. Record how a new pin reaches users before the old pin is retired. A forced update, staged rollout, configuration service, or other mechanism may be appropriate depending on the application design.
For an API client or service
- Inventory every client version and identify which ones enforce pins.
- Confirm whether the client is deployed by your team or by external customers. Customer-controlled software needs a documented pin-distribution process.
- Coordinate certificate, key, load balancer, proxy, and failover changes as one release plan.
- Use monitoring that distinguishes a pin mismatch from an expired certificate, hostname error, trust-chain failure, timeout, or server outage.
- Roll out changes gradually where possible, and retain the old valid path until the new pin is known to work across supported clients.
Pin-rotation worksheet
| Item | Record before deployment |
|---|---|
| Protected hostname and environment | For example, production API, staging API, or regional endpoint |
| Current certificate or public-key identifier | Fingerprint or other precisely defined identifier |
| Backup identifier | Future certificate or key, stored and tested separately |
| Certificate expiration and key-rotation dates | Include the earliest relevant date |
| Client versions in scope | Include minimum supported and rarely updated versions |
| Pin delivery method | Application release, signed configuration, or another controlled mechanism |
| Rollback owner and deadline | Name the responsible team and the decision point |
| Emergency recovery path | Documented action if clients reject the legitimate endpoint |
What to double-check
Certificate chain and hostname: Use an SSL certificate checker or an x509 certificate inspection tool to confirm the complete chain, subject alternative names, validity dates, key usage, and the certificate actually served by every endpoint. A certificate may look correct on one load balancer while another serves an older version.
Pin encoding: Define exactly what is hashed and how it is encoded. A certificate fingerprint, a public-key digest, and a textual certificate representation are different values. Document the format so development, security, and operations teams cannot interpret the pin differently.
Backup independence: A backup pin is not useful if it is simply a duplicate of the primary key or is stored in the same failure domain. Treat it as a planned recovery option, protect its private key, and verify that the client recognizes it before the primary path changes.
Failure behavior: Decide what the client should do when verification fails. It should not silently downgrade to an insecure connection. Provide a safe, observable error state, collect only the diagnostic information permitted by your privacy and security requirements, and ensure support teams can distinguish a pin mismatch from other TLS errors.
Platform and library behavior: Check the TLS library and operating-system documentation used by each supported client. Certificate APIs, trust-store behavior, networking defaults, and update mechanisms vary. Browser-level public-key pinning is not a general solution for websites; application pinning should be limited to clients where the organization can manage the full lifecycle.
Related controls: Pinning does not replace certificate renewal, revocation review, certificate transparency monitoring, secure private-key storage, access control, or incident response. For broader lifecycle planning, see the certificate lifecycle management runbook. For endpoint inspection, see the SSL certificate checker guide.
Common mistakes
- Pinning only the current leaf certificate. This can make a routine renewal fail. If leaf pinning is required, plan the new certificate in advance and distribute it before the old one expires.
- Shipping no backup pin. Without a tested alternative, a lost key or unexpected certificate change may require a rushed application release.
- Adding pins without inventorying endpoints. Redirects, regional hosts, proxies, and failover systems can expose the client to valid certificates that were never included in the design.
- Testing only a clean install. Older installed versions are often the clients most likely to cause a prolonged incident.
- Disabling pinning globally during an incident. A rushed bypass can create a larger security problem. Prefer a reviewed, time-limited recovery mechanism with clear ownership.
- Confusing a valid certificate with an approved identity. Certificate verification confirms properties of the TLS connection; it does not by itself prove that an employee, customer, document signer, or organization is authorized. Use the appropriate identity or credential verification workflow for those decisions.
When to revisit
Review the pinning plan before every certificate renewal, key rotation, application release, infrastructure migration, domain change, or failover redesign. Revisit it during seasonal planning cycles and whenever the TLS library, operating system, networking stack, certificate authority process, or deployment workflow changes.
At each review, repeat the endpoint inventory, inspect the certificate chain, confirm primary and backup pins, test supported client versions, and verify the rollback and emergency recovery path. If the organization can no longer update all pin-enforcing clients reliably, reassess whether pinning still provides more value than operational risk.
Practical next step: copy the pin-rotation worksheet into your change record, assign an owner for each field, and do not retire the old certificate or key until the new pin has been distributed, tested, monitored, and paired with a documented recovery decision.