SSL Pinning Plugin

Stable Version 5.1.1 (O11)
Also available for 10
Published on 2 Sep by 
Created on 16 February 2017

SSL Pinning Plugin

Documentation

In mobile apps, SSL Pinning or HTTP Public Key Pinning (HPKP) provides an extra layer of security to HTTPS communications to avoid, for example, man-in-the-middle attacks. It works client-side and verifies the server certificate by comparing hashes of public keys that are pre-bundled with the mobile app.


Keep in mind that, by design, calls to server actions stop working if there's a hash mismatch. In this case, you need to add a new hash list in the app, build a new version of the app, and distribute it to your users. To anticipate the hash mismatches, design the app so it checks if the certificate is valid or not. See Check hash validity in this page for more information.

The SSL Pinning uses a customized version of the SSL certificate validation, and it doesn't rely on deprecated SSL pinning in browsers.

Important. Don't use the SSL Pinning plugin in production with the default certificate provided by the OutSystems cloud, as your apps will break when OutSystems renews the certificate. In general, you should always use your certificate, for which you have the certificate keys.


How to implement SSL pinning in OutSystems

To implement SSL Pinning it you should have two certificates on the server:

  • One as the primary certificate.

  • The second as backup, in case the primary certificate gets compromised.


The steps to implement SSL Pinning are the following:

  1. Generate hashes for the public keys of the certificates.

  2. Create a configuration file with the hashes.

  3. Install the SSL Pinning from Forge.

  4. Add the configuration file to your mobile app.

  5. Validate the certificates against the hashes in the mobile app.

Generate the hashes for public keys


To generate the hash of a public key in a certificate, get the certificate from the server and use OpenSSL commands to do the following:

  1. Obtain the public key from the certificate.

  2. Calculate hash of the public key using the SHA-256 algorithm.

  3. Encode the hash of the public key in Base64.

Here is an example of the openSSL commands to generate the hash of the certificate public key.

openssl x509 -in my-certificate.crt -pubkey -noout | openssl rsa -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base64


For more examples of the openSSL commands, check out this Mozilla page or this script in GitHub.

Create the configuration file

Create a JSON configuration file and populate it with hashes and the server addresses. Use the following format:


{

    "hosts": [{

        "host": "www.myserver.com",

        "hashes": [

            "sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",

            "sha256/BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB="

            ]

    }]

}


Keep the following notes in mind:

  • The JSON structure must be as provided in this document.

  • The file must have a .json extension, for example, pinning.json.

  • Insert the full hostname of your server.

  • No subdomains are allowed in the host.

  • Each host should have at least two hash keys.

  • Prefix the hashes with sha256/;

  • Only unique hash keys are allowed for iOS.

  • If you're using the OutSystems personal environment, use a dummy text for the second hash key, as there’s only one certificate and hash key available for this environment.


Add the configuration file to the app


Add the configuration file to the mobile app, so the build service can bundle the configuration in the native app build.

In Service Studio, do the following in the mobile app: 

  1. Add a resource with the configuration file. Use only one JSON configuration file as a resource or the Pinning may not work as expected.

  2. Set the Deploy Action property to Deploy to Target Directory.

  3. Set the Target Directory property to pinning (no quotes).


Implement additional verification of the server certificate


To add the SSL Pinning verification, you need to install the SSL Pinning component from the Forge in your environment. 


In Service Studio, do the following in the mobile app:

  1. Go to Manage Dependencies (Ctrl+Q) and add the reference to SSLPinningPlugin.

  2. Drag the RequireSSLPinning block to one of your screens and SSL pinning works for all HTTPS requests in the mobile app. The Splash screen is a good place to add the block.

Check the hash validity


The calls to server actions stop working if there's a hash mismatch. It's a good practice to check for hash validity, and if there's a mismatch, tell the users they need to get the new version of the app. Use the client action CheckCertificateForUrl to check if a hash from the configuration list is valid or not. If the check doesn't pass, show a notification and tell users to install a new version of the app.

By default, the CheckCertificateForUrl action evaluates the URL of the current environment. You can optionally enter a value for the URL parameter. 

The action returns two values:

  • Success. Boolean. True if the connection to the server was successful.

  • Error. Error Structure. Optional, available if there's an error during the request to the server. The values are "SSLPinning found an issue with the configured certificate for the url!" (when there's a problem with the configured hash value) and "Message: SSLPinning found some problem with the request!" (a generic error that requires troubleshooting).


Test the SSL pinning


To test the mobile app with SSL Pinning, do the following:

  1. Publish and generate the new version of your mobile app with SSL Pinning.

  2. Install the app in your smartphone and run. 

  3. Verify that app works, as it has the right certificate and hash keys.


To see SSL pinning in rejecting a certificate, do the following:

  1. Edit the configuration file and tamper with the hashes. For example, change one character in each hash.

  2. In your mobile app:

    1. Remove the resource with the old configuration file.

    2. Add a resource with the new configuration file (don’t forget to set the properties).

    3. Publish and generate the new version.

  3. Install the new version in your smartphone and run.

  4. The mobile app won’t work because the SSL inning raises an error due to an invalid certificate.


SSL pinning for multiple servers


If you want your mobile app to perform SSL pinning validations while connecting to multiple servers:

  1. For each server, get its two certificates and generate their hashes.

  2. Create the configuration file in the following JSON format:

{

    "hosts": [{

        "host": "www.myserver1.com",

        "hashes": [

            "sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",

            "sha256/BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB="

            ]

    },{

        "host": "www.myserver2.com",

        "hashes": [

            "sha256/CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC=",

            "sha256/DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD="

            ]

    },

      ...

      ]

}


  1. Bundle the configuration file and implement the verification in your mobile app as explained for a single server.


Plan for the certificate renewal


If you're planning to update your certificate soon, release a new version of the app with the JSON configuration that contains the hash values for both the current certificate and the new certificate. Do this before you update the certificate, to give enough time to your users to update the app. This way, once you update the certificate, the app continues to work.


Limitations


Blob object and Android

Currently, handling Blob objects is not supported in Android when SSL Pinning is enabled.


Support Options
OutSystems Supported
Customers entitled to Support Services may obtain assistance through Support.
Dependencies
See all 1 dependencies