You are here: Adding Functionality > Apply Application Security > Certificate Pinning

Certificate Pinning

To check trust for communication between an app and a server, server certificates are bundled with the application. Pinning is a process of associating a host with their expected certificate or public key. Once a certificate or public key is known or seen for a host, the certificate or public key is associated or pinned to the host.

Pinning makes use of knowledge of the pre-existing relationship between the user and an organization or service to make the security-related decisions better. As the information is already on the server or service, you do not need to rely on generalized mechanisms meant to solve the key distribution problem. You do not need to turn to DNS for name/address mappings or CAs for bindings and status.

In this document, you will learn about the following topics: 

  1. Get the Certificate that you want to Pin
  2. Enable Certificate Pinning in iOS
  3. Enable Certificate Pinning in Android
  4. Enable Certificate Pinning in Windows

Get the Certificate that you want to Pin

To get the certificate that is to be pinned, follow any of these two procedures which are common for all platforms:

Generate by using the KonySSLPinningTool.jar Tool

Follow these steps to use the KonySSLPinningTool.jar file:

  1. Download the zipped KonySSLPinningTool.jar file to your local system, and then unzip it.

Note: You must run the KonySSLPinningTool.jar file with Java 8 or later.

  1. Run the following command to save the entire certificate chain from leaf to root individual cert files in der format:
    java -jar KonySSLPinningTool.jar --cert_format DER --ssl_host HOST_NAME --ssl_port PORT
    here, HOST_NAME: The host name of your server.
    PORT: HTTPS port on which your server is listening. It defaults to 443, if --ssl_port option is not specified.

All the certificates are saved with their common name (CN) as the file names after replacing the non-alpha numeric characters with underscore ( _ )

Note: The Windows platform respects only .cer extension for certificates. So, you must change the extension of the generated certs from .der to .cer before performing pinning in the application.

You can get additional information on the supported command line arguments by using this command: java -jar KonySSLPinningTool.jar –help

Retrieve Certificates through openssl Command or Browser

Follow these steps to retrieve the certificate by using either the openssl command or by using any web browser:

Note: The certificate that you choose for pinning impacts the level of security you achieve. The security level decreases as you navigate up the certificate chain from leaf to root certificate. You can pin either the leaf certificate in chain, or the intermediate CA certificate, or pin both the leaf and intermediate CA certificates simultaneously. Typically, the intermediate CA certificate is your organizational CA certificate.

Enable Certificate Pinning in iOS

Follow these steps to enable Certificate Pinning in iOS:

  1. Bundle the certificate in the application.
    1. Navigate to the application resources folder and create a certs folder in it.
    2. certs folder need to be created in the following path:

      1. <workspace>/<app>/resources/mobile/native/iphone/

      2. <workspace>/<app>/resources/tablet/native/ipad/

    3. Place server certificates inside the certs folder.
  2. Configure SSL Pinning.
    1. In infoplist_configuration.json file, add the entry { "allowbundledonly" = true }. For more information on how to configure custom key value pairs in iOS platform, click here.

Enable Certificate Pinning in Android

Follow these steps to enable Certificate Pinning in Android:

  1. Navigate to the application resources folder.
  2. Copy the server certificate to the certs folder as shown. Create the folder hierarchy, if required.
    • For mobile - <workspace>/<app>/resources/mobile/native/android/assets/certs/

    • For tablet - <workspace>/<app>/resources/tablet/native/androidtab/assets/certs/

  3. In Kony Studio, right-click your application and go to Properties > Native > Android.
  4. From the Network Trust Config (or) Allow Self Signed/Untrusted Certificates drop-down list, select Allow Pinned.
  5. Build the application for Android platform.

Enable Certificate Pinning in Windows

Follow these steps to enable Certificate Pinning in Windows:

  1. Navigate to the application resources folder.
  2. Copy the server certificate to the certs folder as shown. Create the folder hierarchy, if required.
    • For mobile - <workspace>/<app>/resources/mobile/native/winphone8/assets/certs/
    • For tablet - <workspace>/<app>/resources/tablet/native/windows8/assets/certs/
  3. For the mobile channel in Kony Studio, right-click your application and go to Properties > Native > Windows Phone > Common.
  4. For tablet channel in Kony Studio, right-click your application and go to Properties > Native > Windows Tablet > Application UI.
  5. From the Network Trust Config (or) Allow Self Signed/Untrusted Certificates drop-down list, select Allow Bundled.
  6. Build the application from Windows platform.
Copyright © 2020 Temenos. All rights reserved.