Certificate pinning

Last updated: October 15, 2024

Certificate pinning is the process of associating a host with their expected certificate or public key. This increases security by protecting against certificate misuse, certificate authority compromise, and man-in-the-middle attacks.

Default behavior

By default, the iProov biometric SDKs pin to the public key of our intermediate certificate provided by AlphaSSL. This is used by iproov.me, the host name of our global streaming platform.

When should I use certificate pinning?

The iProov SDK can set a custom certificate to pin to, for example, if you are using your own reverse proxy for streaming. Add the provided certificates to your app bundle as a DER-encoded X.509 certificate.

Important

The iProov SDK pins to the public key of the certificate.

Multiple certificates

The SDK can pin to multiple certificates. If you have a .cer file, use this command to convert to a .der file:

openssl x509 -in {cert.crt} -outform der -out {cert.der}

How does certificate pinning work?

The process for determining the validity of pinned certificates is as follows:

  1. The domain names of the pinning certificates are checked against the host domain.

  2. The public keys of the pinning certificates are extracted and compared against the public keys of each certificate in the host's chain.

If any of the certificates in the host's chain have the same public key as any of the pinning certificates, and the domain matches, the connection is allowed.

Certificate pinning can be disabled for testing and development, however, this is strongly discouraged for production.

Android SDK implementation

v8.0.0 and later

options.certificates

For example:

options.certificates = arrayOf(R.raw.iproov__certificate)

v7.5.0 and earlier

options.network.certificates

For example:

options.network.certificates = arrayOf(R.raw.iproov__certificate)

Can be applied as either:

  • A list of resources IDs.

  • The contents of certificates as a list of byte arrays.

Generate certificates in DER-encoded X.509 certificate format.

Default: R.raw.iproov__certificate

See: Android network options

iOS SDK implementation

v10.0.0 and later

options.certificates

For example:

options.certificates = [Bundle.main.path(forResource: "custom_cert", ofType: "der")!]

Array elements must be of the type: Data (the certificate itself)

 

v9.5.1 and earlier

options.network.certificates

For example:

options.network.certificates = [Bundle.main.path(forResource: "custom_cert", ofType: "der")!]

Array elements can be one of the following types:

  • String (path to certificate)

  • Data (the certificate itself)

Pass certificates in DER-encoded X.509 certificate format.

See: iOS network options

Web SDK implementation

This feature is not applicable with the iProov Web SDK. Use built in browser technologies instead, for example:

  • HSTS

  • Content-Security-Policy

  • Feature-Policy

  • Cross-origin protections

Next step

Reverse proxies