Decide whether pinning solves your threat
A conventional HTTPS client already validates a server certificate against its trust configuration. Pinning adds a narrower trust decision, but also ties installed application versions to your certificate operations. Android's network security guidance cautions against casual pinning because certificate changes can break connectivity.
Certificate pinning is still widely called SSL pinning; both names describe the same public-key pin check, even though TLS is the current protocol term.
Write down the attacker capability you are addressing and the certificate changes you can operationally control. A public content app and a managed financial client may reach different decisions. Do not add pinning simply to make a scanner finding disappear.
Pin public keys with an exit plan
A declarative pin set lives inside a domain configuration. The following is a structural illustration, not a usable certificate value:
<pin-set expiration="2027-09-22">
<pin digest="SHA-256">BASE64_PRIMARY_SPKI_SHA256</pin>
<pin digest="SHA-256">BASE64_BACKUP_SPKI_SHA256</pin>
</pin-set>
Replace placeholders with independently verified public-key hashes. A backup pin should correspond to a key you can actually deploy, not a second copy of the current certificate. An expiration changes the protection after that date; it is not a maintenance reminder alone.
Test the certificate lifecycle
Use a controlled endpoint and a release-like build to test the present key, planned replacement key, unrelated valid certificate and expired certificate. Record expected outcomes before running the tests.
| Change | Question to answer |
|---|---|
| Certificate renewed with same key | Does the intended pin still validate? |
| Key rotated | Can existing installed versions connect? |
| CDN or regional endpoint changes | Are all legitimate chains covered? |
| Emergency certificate replacement | Is there an executable recovery procedure? |
A successful debug connection is insufficient when debug trust overrides differ from release configuration.
Avoid a dangerous “fix”
Do not solve a pin failure with a trust-all certificate manager or a hostname verifier that always returns true. Diagnose the requested hostname, certificate chain, device clock and actual client implementation first. A native network stack may not use the same declarative configuration as a framework client.
Inspect configuration, then verify behavior
APKLint's Network Security Config Checker can help review the XML structure and broad trust exceptions. It cannot prove that the live endpoint rotates safely or that every networking library honors that configuration. Keep the test evidence and certificate ownership record alongside the application release.
Include older installed clients in the rotation plan
Suppose release A trusts the current public key and a planned backup, while release B introduces a future replacement. Test both client versions against each certificate chain that the service may present during migration. A new client connecting successfully says nothing about users who still run release A. Keep the server rollout decision tied to the oldest supported installed configuration.
The Network Security Configuration reference explains public-key pins, backup keys and expiration. A pin is a hash of the appropriate public-key structure, not an APK signing fingerprint or a hash of the entire downloaded certificate file. Verify the calculation independently before treating a connection failure as a platform bug.
Test every legitimate certificate presentation
List the API, upload and regional hosts used by the client. If a content-delivery provider or load balancer can present different valid chains, include those presentations in the controlled test. A sample connection to one hostname and region does not cover an endpoint the app reaches only during an upload or failover.
Use a release-like configuration for the decisive tests. A development trust override can change pin enforcement and make a proxy connection appear to prove the production pin set works. Record the packaged configuration and debuggable state alongside the result, so the trust assumptions are visible to the person approving the certificate change.
Define an observable failure state in the app. If a secure connection is rejected, show a bounded retry or service-unavailable result without disabling certificate or hostname validation. An automatic retry loop should not consume the battery while offering no recovery path. Preserve a non-sensitive diagnostic category and the affected endpoint name rather than request credentials.
Before the planned rotation, rehearse the documented recovery procedure on the test service with the retained client artifacts. Establish who can deploy the backup key and what evidence shows that older clients remain supported. The operational value of a backup pin comes from a deployable key and tested process, not from having two different-looking strings in an XML file.
Sources and further reading
Reference review: 29 September 2026. Examples illustrate the workflow; check your installed versions, release artifact and account-specific Console requirements before applying them. This guide is not a claim that APKLint executed your project or verified your private account.
Android inspection tools and practical release guides. About APKLint · Report a correction
