Integrate SSL pinning

Prev Next

The SSL pinning feature verifies the public keys of servers before allowing communication. A list of accepted public key of certificates is embedded inside the application, and any HTTPS request to a host that is not pinned will be refused.

Enabling SSL pinning

To enable SSL pinning, add an identityPinning entry under config > features in your customization file:

"identityPinning": {
  "domain": "example.com",
  "keys": [
    "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
  ]
}

where

  • domain is the server’s host name to pin. Pinning applies to this domain and all its subdomains.

  • keys are one or more public keys in the SPKI-SHA256-BASE64 format.

Generating the SPKI-SHA256-BASE64 value

The keys value is the Base64-encoded SHA-256 hash of the DER-encoded Subject Public Key Info (SPKI) of the server certificate.

  • To generate the SPKI value from a PEM certificate, run the following command:

    openssl x509 -in certificate.pem -pubkey -noout \
      | openssl pkey -pubin -outform der \
      | openssl dgst -sha256 -binary \
      | openssl enc -base64
  • To generate the SPKI value from a Java keystore, first export the certificate as PEM, then run the command:

    keytool -export -alias MyCertificateAlias -keystore MyKeyStore.keystore -rfc -file certificate.pem
    openssl x509 -in certificate.pem -pubkey -noout \
      | openssl pkey -pubin -outform der \
      | openssl dgst -sha256 -binary \
      | openssl enc -base64

The output is a Base64 string that you can paste directly into the keys array.

We recommend including at least two keys (the current certificate and a backup) to ensure that a certificate rotation does not break the app for existing users.