Open topic with navigation

You are here: Adding Functionality > Apply Application Security > Public Key Pinning

Public Key Pinning

SSL Pinning

SSL Pinning is the process of associating a host with their expected X509 certificate or a public key. Once a host's certificate or public key is known or identified, the certificate or public key is associated or 'pinned' to the host. This offers protection against certificate forgery.

You have to take the following decisions in the pinning process:

Public Key Pinning

Kony has previously rolled out the Certificate Pinning feature. The drawback of Certificate Pinning is that when the server rotates its certificate on a regular basis, you would need to update the application regularly as well.

The Public Key Pinning feature addresses the downside of certificate pinning. By using key pinning, you can avoid frequent application updates as the pubic key can remain same for longer periods.

So if you want to minimize your maintenance efforts and still want a secure communication through your application, then leveraging the HTTP Public Key Pinning feature is the best solution.

Note: For Android, you can alternatively achieve Public Key Pinning by using Android Network Security Configuration for API level 24 and later. To learn more about the differences between the Kony Public Key Pinning and Android Network Security Configuration features, click here.

Enable Public Key Pinning

To enable the Public Key Pinning feature for a Kony application, follow these steps:

  1. In your Kony Visualizer project, from the Project Explorer, click Project Setings. The Project Settings window appears.

  2. Click the Native tab. A horizontal list of sub-tabs appears under Native.
  3. Follow these steps for the required platform:
    • For Android: Go to Android > Mobile/Tablet. From the Network Trust Config drop-down list, select Allow Pinned.
      If the Allow Pinned option is not available in Visualizer, you can manually specify the networktrustconfig property in the androidbuild.properties file.
    • For Windows Phone: Go to Windows Phone > Common. From the Network Trust Config drop-down list, select Allow Pinned.
    • For Windows Tablet: Go to Windows Tablet > Application UI. From the Network Trust Config drop-down list, select Allow Pinned.
    • For iOS: In infoplist_configuration.json file, add the entry { "KonyHTTPPublicKeyPinning" = true }. For more information on how to configure custom key value pairs in iOS platform, click here.

In addition, you must provide the <workspace>/<platform-specific-path-to-certs>/public_keys.json file. This file contains all the information on the domain versus the pins configuration (the JSON format is explained in the next section).

Path of public_keys.json file in different Platforms and Channels

In iOS

In Android

In Windows

Note: Make sure the file name containing SSL Pinning Public Keys is in the exact public_keys.json case.

Format of the JSON File for the Public Keys (certs/public_keys.json)

{
    "domain-expression1": [
        "sha256-pin1",
        "backup-sha256-pin2",
        // ...
    ],

    "domain-expression2": [
        "sha256-pin3",
        "backup-sha256-pin4",
        // ...
    ],
    // ...
}

Domain Name (Expression) Rules

The rules for the domain names/expressions in the public_keys.json file are as follows:

Example

{
    "*.kony.com": [
        "rSV28bZT885DlLB9/wTzyMuYG+VdA0OlRjjzC72rxno=",
        "JSMzqOOrtyOT1kmau6zKhgT676hGgczD5VMdRMyJZFA="
    ],

    "manage.kony.com": [
        "HA8d0iApa5nQhToDQIcwYQmDYi1rd07MLck8Px4+31B=",
        "JSMzqOOrtyOT1kmau6zKhgT676hGgczD5VMdRMyJZFA="
    ],

    "*.amazon.in": [
        "VkvE/TdvozXh8Frp01wrxI0nh63JIE7FKRt2EQ+Phew="
    ]
}

Remarks

Generate SPKI Pin Hash

To generate the SPKI Pin Hash from the certificate, follow one of these procedures:

Generate by using the KonySSLPinningTool.jar Tool

Follow these steps to use the KonySSLPinningTool.jar file and generate SPKI hashes:

  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 generate SPKI Pins Hashes for the entire certificate chain from leaf to root:
    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.
    This command prints the SPKI hashes on the console and saves them to a file.

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

Retrieve Certificate and Generate SPKI Pin Hash from the Certificate

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

Note: This command may return a different certificate when the server supports Server Name Indication (SNI).
So while using with servers that support SNI, you must ensure that the openssl version is 1.1.1a or 1.0.2q or later, which has SNI extension enabled by default, or alternatively, use Browser to fetch certificates.

Note: You can verify the Open SSL version by using the following command: openssl version

Android Network Security Configuration

As a security improvement , apps that target Android 7.0 (API level 24 and later) and later will no longer trust user-installed certificates on devices with Android 7.0 and later.

From Android 7.0 devices and later, Android has offered a way to customize app behavior for all secure HTTPS communications that originate out of the application (including the WebView/Browser widget network calls) without touching the application code. This is achieved by using a Network Security Configuration that is defined as an xml resource (network_security_config.xml file) in the application.

This xml file helps you to customize the following features in the application:

Note: For the apps that target Android 9 PIE or later (API level 28 or later), all HTTP communications are disabled by default.

For more information on the usage of the Android Network Security Configuration feature, refer the following links:

Add Android Network Security Configuration

If you want to add support for the Network Security Configuration feature to your existing Kony Andorid project, follow these steps:

Note: This feature works only for devices with Android API level 24 and later.

  1. In Kony Visualizer, go to Project Settings > Native >Android >Tags >Application Tag Attributes.

  2. Add the following application tag entry in the app’s Manifest file:
    android:networkSecurityConfig="@xml/network_security_config"

  3. Add the network_security_config.xml file in the following path, as appropriate:

    • For mobile: <vizproject>/<app>/resources/mobile/native/android/xml/network_security_config.xml
    • For tablet: <vizproject>/<app>/resources/tablet/native/android/xml/network_security_config.xml

Kony Public Key Pinning vs. Android Network Security Configuration

The following table illustrates the differences between Kony HTTP Public Key Pinning and Android Network Security Config.

Difference Aspect Kony Public Key Pinning Android Network Security Configuration
Support Scope kony.net.* JS APIs Entire application including kony.net.* , FFI network calls, and WebViews (including Kony Browser widget)
Hosts Allowed Network calls to non-pinned hosts fail by default, which is in line with the certificate pinning feature and the pinned hosts are allowed after the pin is successfully validated Network calls to non-pinned hosts are also allowed
Can Certificate Pinning and Public Key Pinning be applied at the same time? Mutually Exclusive Both can be configured simultaneously
Precedence when both features are configured Respected after Android Network Security Configuration (if already configured) rules are applied Takes first precedence.
Pin Generation Mechanism SPKI (Subject Public Key Info) SPKI (Subject Public Key Info)
Supported Andorid Versions 17 and later (Android 4.2.x) 24 and later (Android 7)
Supported Kony Versions V8 SP4 onwards Applicable in any Kony version

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Rev Author Edits
7.0 NMK NMK
Copyright © 2013 Kony, Inc. All rights reserved.

Open topic with navigation