Certificate pinning
Last reviewed: 10 November 2026
We advise against certificate pinning. It is a common cause of outages and it adds little protection on top of the TLS checks that Android and iOS already do. Only enable it if your security or compliance rules require it.
If you enable certificate pinning, you take on all the risk of service interruption that comes with it. This applies to any change to the certificates you pinned, or to our certificate provider, planned or unplanned. AWS and Entrust give notice of such changes on a best-effort basis only. Read Risks you accept before you enable it.
Many in the industry now advise against pinning:
- AWS, who issues our certificates, says: "We recommend that your application not pin an ACM certificate." (AWS Certificate Manager best practices)
- Cloudflare reported a sharp rise in customer outages caused by pinning in 2024, after certificate authorities started to rotate their certificates more often. Their article also explains the limits of each pinning option: Avoiding downtime: modern alternatives to outdated certificate pinning practices.
What pinning protects against
Pinning blocks a connection when the device trusts the server's certificate, but the certificate does not chain to a key you pinned. In practice, this covers two cases:
- A certificate installed on the device, for example by a company network or security software that inspects traffic. How far the platform already protects against this depends on how the certificate was installed:
- On iOS, a certificate the user installs by hand is trusted only after the user turns this on in Settings. A certificate installed through device management (MDM) is trusted automatically.
- On Android, apps that target Android 7 (API level 24) or later, which is almost all apps today, do not trust certificates added by the user or by device management, unless the app's network security config allows them.
- A certificate issued for our hosts by mistake by another certificate authority. Our DNS records (CAA) list the certificate authorities allowed to issue certificates for our domains, and certificate authorities must check them before they issue one. Certificate authorities also publish the certificates they issue in public Certificate Transparency logs, so a certificate issued by mistake can be detected.
These safeguards already limit both cases, although not completely, for example on company-managed iOS devices. For most apps, this leaves little for pinning to add, while pinning adds a real risk of outages.
Pinning does not protect against someone who controls the device. On a rooted or jailbroken device, or with tools that change the app while it runs, the check can be bypassed and the traffic read or changed.
How certificate pinning works
When pinning is enabled, the SDK checks the certificate chain of the Entrust API host it connects to. The connection is allowed only if the public key of at least one certificate in the chain matches one of the hashes you provide. This check runs in addition to the normal system checks, not instead of them.
The API host is the one your SDK token points to: api.onfido.com, api.eu.onfido.com, api.us.onfido.com or api.ca.onfido.com, depending on the region of your account.
Pinning a certificate or its public key
Every certificate contains a public key, in a field called SubjectPublicKeyInfo (SPKI). There are two ways to pin:
- Pin the certificate. The pin matches one exact certificate. It breaks whenever that certificate is replaced, even if the new one uses the same key.
- Pin the public key (SPKI pinning). The pin matches the key inside the certificate. It keeps working when the certificate is renewed, as long as the new certificate uses the same key.
The SDK uses SPKI pinning: each hash is the SHA-256 hash of a certificate's SPKI. This guide uses "certificate pinning" because it is the common name for both.
AWS creates a new key every time it renews our certificates, so a pin on our server's public key breaks at every renewal, the same as a pin on the certificate itself. This is why we recommend pinning the public keys of the Amazon roots, which change much less often. See What to pin.
What is not covered
Pinning does not make the whole flow pinned. It applies only to the native SDK's requests to the API host. It does not cover:
- Web modules. Screens that run in a web view, and everything they load, including their own requests to the API host.
- Content hosts
sdk.onfido.comandassets.onfido.com, which the SDK uses for files such as translations, animations and models. - DNS-over-HTTPS lookups made by the Android SDK.
- Third-party hosts that some modules use.
- Your own backend, including the requests that create applicants, workflow runs and SDK tokens.
What to pin
Pin the public keys of the Amazon root CAs. Our certificates are issued and renewed automatically by AWS Certificate Manager and chain to the Amazon Trust Services roots.
| Certificate | Valid until | Hash |
|---|---|---|
| Amazon Root CA 1 | 17 Jan 2038 | sha256/++MBgDH5WGvL9Bcn5Be30cRcL0f5O+NyoXuWtQdX1aI= |
| Amazon Root CA 2 | 26 May 2040 | sha256/f0KW/FtqTjs108NpYj42SrGvOB2PpxIVM8nWxjPqJGE= |
| Amazon Root CA 3 | 26 May 2040 | sha256/NqvDJlas/GRcYbcWE8S/IceH9cq77kg0jVhZeAPXq8k= |
| Amazon Root CA 4 | 26 May 2040 | sha256/9+ze1cZgR9KO1kZrVDxA4HQ6voHRCSVNz4RdTCx4U8U= |
We recommend pinning all four. Our certificates chain to Amazon Root CA 1 today. The other three are backups in case AWS moves our certificates to another Amazon root. This list is not guaranteed to be complete: a move to a root that is not listed here will still break pinned apps.
You can check these hashes yourself. Download the certificates from the Amazon Trust Services repository and run:
1openssl x509 -in AmazonRootCA1.pem -noout -pubkey \2 | openssl pkey -pubin -outform der \3 | openssl dgst -sha256 -binary \4 | openssl enc -base64
Do not pin our server or intermediate certificates
The SDK accepts any correctly formatted hash, but we do not support pins on anything other than the roots above. They will break:
- Server (leaf) certificates get a new key every time they are renewed. Renewal is automatic and will happen more often: under CA/Browser Forum rules, certificates are valid for at most 200 days today, 100 days from March 2027 and 47 days from March 2029.
- Intermediate certificates change without notice. AWS issues certificates from a large and growing set of intermediates, some valid for only three years, and the one used for our hosts can change at any renewal. This has already happened on our hosts.
Limits of root pinning
Root pinning is the only option we support, but it has limits you should know about:
- Broad trust. A root pin trusts every certificate issued under that root. Amazon uses the same roots and intermediates for all its customers, but it only issues a certificate for our hosts to us, after checking that we control the domain. So a root pin blocks certificates from any other certificate authority, and from proxies or certificates installed on the device, such as those used by some company networks or security software. It does not block a certificate that Amazon issues for our hosts by mistake. Only pinning our server certificate would cover that, and we do not support it because it breaks at every renewal. Cloudflare calls this "broader trust".
- Roots change too. Rarely, but they do. Browser root programs now limit how long a root can be used (Chrome removes roots 15 years after their key was created). Amazon Root CA 1 dates from 2015, so Amazon may need to move to newer roots well before the dates in the table.
- Providers change. Certificate authorities and providers can change. Any such change breaks existing pins.
How to enable certificate pinning
Certificate pinning is available from Android SDK 100.16.0 and iOS SDK 100.19.0. Support for React Native and Flutter will follow.
certificatePinning {CertificatePinning}- optional (defaultnull, pinning off)publicKeyHashes {List<String>}- required whencertificatePinningis set. At least 2 different hashes. Each one issha256/followed by the base64 SHA-256 hash of the certificate's public key (SubjectPublicKeyInfo).
We strongly recommend loading the hashes from your backend or remote config instead of hard-coding them. It is the only way to recover from a pinning outage without releasing a new version of your app. Roll out changes to your hashes gradually, to a small share of users first. See If your users are blocked.
1entrustIdv.start(2 ...3 configuration = Configuration(4 ...5 certificatePinning = CertificatePinning(6 publicKeyHashes = pinsFromRemoteConfig, // e.g. the 4 hashes above7 ),8 )9)
1EntrustIdv(2 ...3 configuration: .init(4 ...5 certificatePinning: CertificatePinning(publicKeyHashes: pinsFromRemoteConfig)6 )7)
To turn pinning off, leave out certificatePinning.
We recommend controlling this with a remote switch, for example a flag in your remote config. If a certificate change breaks pinning, turn the switch off. Your users can complete the flow again the next time they start the SDK, while you update your hashes. You do not need to release a new version of your app.
Protect your remote config before you rely on it for pinning. If an attacker can change it, or intercept the connection that loads it, they can turn pinning off or replace your hashes with their own before the SDK starts. For example, pin the connection to your config backend with hashes built into your app, not loaded from the same config. If loading the config fails, keep the last hashes you had. Do not turn pinning off.
Certificate pinning errors
When the SDK starts. If the configuration is not valid, the SDK does not start and calls onError with InvalidSdkParameter (category Initialisation). The message says what is wrong:
certificatePinning.publicKeyHashes must not be emptycertificatePinning.publicKeyHashes must contain at least 2 distinct pinscertificatePinning.publicKeyHashes[<index>] is not a valid sha256/ pin
During the flow. If the API host's certificate chain does not match any of your hashes, the request is blocked and not retried. The SDK calls onError with CertificatePinningFailed (category Network). The user cannot continue the flow.
We recommend reporting CertificatePinningFailed to your own monitoring, so you find out about a problem before your users report it.
Risks you accept
By enabling certificate pinning, you accept that:
- Pinning can cause a service interruption, and over time it is likely to. Roots, intermediates and providers change, and certificates are renewed automatically and more often.
- Our certificates are managed by AWS. AWS gives notice of changes on a best-effort basis only, and may change certificates at any time, including in an emergency.
- Entrust cannot commit to any notice period either. We try to update the hashes on this page when we learn about a change, but this is best effort.
- Entrust cannot fix a pinning failure on our side. The SDK has no remote switch to turn pinning off, and we cannot undo a certificate change made by AWS.
- Pinning in the SDK is only as strong as your app's own setup. If an attacker can change the hashes or the switch your app passes to the SDK, for example through your remote config, they can turn pinning off or replace your hashes. Protecting them is your responsibility.
- You are responsible for keeping your pins up to date, and for any interruption pinning causes to your users, whether the change was planned or not.
To keep the risk low:
- Pin all four Amazon roots. Never pin a leaf or intermediate certificate.
- Load the hashes from your backend or remote config, so you can change them or turn pinning off without an app release.
- Add a remote switch that turns pinning off, and make sure your team knows how to use it.
- Check this page regularly, not only before an app release, and update your hashes when it changes. The "Last reviewed" date at the top shows when we last checked the hashes.
- If your hashes are hard-coded, make sure you can force users to update your app.
If your users are blocked
If your users see CertificatePinningFailed:
-
Check which certificates the API host serves now, and compare their hashes with your pins:
shell1openssl s_client -connect api.eu.onfido.com:443 -servername api.eu.onfido.com -showcerts </dev/nullSave each certificate from the output to a file and run the hash command from What to pin on it. Use the API host of your region. If one of the hashes matches your pins, our chain is not the cause. See steps 4 and 5.
If none of the hashes match, find the root of the chain. The server may not send the root itself. If the subject (
s:) of the last certificate is an Amazon root, that is the root. Otherwise, the root is the issuer (i:) of the last certificate.- If it is one of the roots in What to pin and its hash is not in your pins, add its hash from the table to your pins. If it is already in your pins, our chain is not the cause. See steps 4 and 5.
- If it is another Amazon root, download it from the Amazon Trust Services repository, hash it and add the hash to your pins.
- If it is not an Amazon root, contact Customer Support before you change anything.
This check works even if this page has not been updated yet.
-
If your hashes come from your backend or remote config, update them to the hashes on this page, or remove
certificatePinningto turn pinning off. Users recover the next time they start the SDK. -
If your hashes are hard-coded, release an app update with the new hashes, or with pinning off, and force users to update. Users on older versions of your app cannot complete verification until they update.
-
If only some users are affected, check whether they are on a network that inspects TLS traffic, such as some company networks or security software. Pinning blocks these connections on purpose.
-
If you still cannot find the cause, contact Customer Support with the platform, SDK version, API host (region) and the time the errors started.
Migrating from the Onfido SDK
- As before, only root pins are supported.
- Every hash needs the
sha256/prefix. The iOS Onfido SDK accepted hashes without it. - SHA-1 hashes are no longer accepted. The Android Onfido SDK accepted them.
- At least 2 different hashes are required. One hash is rejected when the SDK starts.
- On iOS, pinning errors are reported as
CertificatePinningFailed, not asinvalid_certificate.


