com.datatheorem.android.trustkit

Class TrustKit

java.lang.Object

com.datatheorem.android.trustkit.TrustKit

public class TrustKit
extends java.lang.Object

Class that provides all of the TrustKit public APIs.

It should be used to initialize the App's SSL pinning policy and to retrieve the corresponding SSLSocketFactory and X509TrustManager, to be used to add SSL pinning validation to the App's network connections.

TrustKit works by extending the Android N Network Security Configuration in two ways:

• It provides support for the SSL pinning functionality of the Android N Network Security Configuration to earlier versions of Android, down to API level 17. This allows Apps supporting versions of Android that earlier than N to implement SSL pinning in a way that is future-proof.
• It adds the ability to send reports when pinning validation failed for a specific connection. Reports have a format that is similar to the report-uri feature of HTTP Public Key Pinning and TrustKit iOS.

For better compatibility, TrustKit will also run on API levels 15 and 16 but its functionality will be disabled.

Supported Android N Network Security Settings

On devices before Android N, TrustKit supports the following XML tags defined in the Android N Network Security Configuration for deploying SSL pinning:

• <domain-config>.
• <domain> and the includeSubdomains attribute.
• <pin-set> and the expiration attribute.
• <pin> and the digest attribute.
• <debug-overrides>.
• <trust-anchors>, but only within a <debug-overrides> tag. Hence, custom trust anchors for specific domains cannot be set.
• <certificates> and the overridePins and src attributes. Only raw certificate files are supported for the src attribute (user and system values will be ignored).

On Android N devices, the OS' implementation is used and all XML tags are supported.

Additional TrustKit Settings

TrustKit provides additional functionality to not enforce pinning validation and to allow reports to be sent by the App whenever a pinning validation failure occurred.

<trustkit-config>

The main tag for specifying additional TrustKit settings, to be defined within a <domain-config> entry. It supports the following attributes:

• enforcePinning: if set to false, TrustKit will not block SSL connections that caused a pinning validation error; default value is false. When a pinning failure occurs, pin failure reports will always be sent to the configured report URIs regardless of the value of enforcePinning. This behavior allows deploying pinning validation without the risk of locking out users due to a misconfiguration, while still receiving reports in order to assess how many users would be affected by pinning.
• disableDefaultReportUri: if set to true, the default report URL for sending pin failure reports will be disabled; default value is false. By default, pin failure reports are sent to a report server hosted by Data Theorem, for detecting potential CA compromises and man-in-the-middle attacks, as well as providing a free dashboard for developers; email info@datatheorem.com if you'd like a dashboard for your App. Only pin failure reports are sent, which contain the App's package name, a randomly-generated ID, and the server's hostname and certificate chain that failed validation.

<report-uri>

A URL to which pin validation failures should be reported, to be defined within a <trustkit-config> tag. The format of the reports is similar to the one described in RFC 7469 for the HPKP specification. A sample TrustKit report is available in the project's repository .

Sample TrustKit Configuration

The following configuration will pin the www.datatheorem.com domain without enforcing pinning validation, and will send pinning failure reports to report.datatheorem.com. It also defines a debug overrides to add a debug certificate authority to the App's trust store for easier debugging of the App's network traffic.

     
         <!-- res/xml/network_security_config.xml -->
         <?xml version="1.0" encoding="utf-8"?>
         <network-security-config>
         <!-- Pin the domain www.datatheorem.com -->
         <!-- Official Android N API -->
         <domain-config>
         <domain>www.datatheorem.com</domain>
         <pin-set>
         <pin digest="SHA-256">k3XnEYQCK79AtL9GYnT/nyhsabas03V+bhRQYHQbpXU=</pin>
         <pin digest="SHA-256">2kOi4HdYYsvTR1sTIR7RHwlf2SescTrpza9ZrWy7poQ=</pin>
         </pin-set>
         <!-- TrustKit Android API -->
         <!-- Do not enforce pinning validation -->
         <trustkit-config enforcePinning="false">
         <!-- Add a reporting URL for pin validation reports -->
         <report-uri>http://report.datatheorem.com/log_report</report-uri>
         </trustkit-config>
         </domain-config>
         <debug-overrides>
         <trust-anchors>
         <!-- For debugging purposes, add a debug CA and override pins -->
         <certificates overridePins="true" src="@raw/debugca" />
         </trust-anchors>
         </debug-overrides>
         </network-security-config>
     
 

Method Summary

Modifier and Type	Method and Description
com.datatheorem.android.trustkit.config.TrustKitConfiguration	getConfiguration() Retrieve the current TrustKit configuration.
static TrustKit	getInstance() Retrieve the initialized instance of TrustKit.
javax.net.ssl.SSLSocketFactory	getSSLSocketFactory(java.lang.String serverHostname) Retrieve an SSLSSocketFactory that implements SSL pinning validation based on the current TrustKit configuration for the specified serverHostname.
javax.net.ssl.X509TrustManager	getTrustManager(java.lang.String serverHostname) Retrieve an X509TrustManager that implements SSL pinning validation based on the current TrustKit configuration for the supplied hostname.
static TrustKit	initializeWithNetworkSecurityConfiguration(android.content.Context context) Initialize TrustKit with the Network Security Configuration file at the default location res/xml/network_security_config.xml.
static TrustKit	initializeWithNetworkSecurityConfiguration(android.content.Context context, int configurationResourceId) Initialize TrustKit with the Network Security Configuration file with the specified resource ID.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

initializeWithNetworkSecurityConfiguration

@NonNull
public static TrustKit initializeWithNetworkSecurityConfiguration(@NonNull
                                                                           android.content.Context context)

Initialize TrustKit with the Network Security Configuration file at the default location res/xml/network_security_config.xml. The Network Security Configuration file must also have been added to the App's manifest.

Parameters:

context - the application's context.

Throws:

com.datatheorem.android.trustkit.config.ConfigurationException - if the policy could not be parsed or contained errors.

initializeWithNetworkSecurityConfiguration

@NonNull
public static TrustKit initializeWithNetworkSecurityConfiguration(@NonNull
                                                                           android.content.Context context,
                                                                           int configurationResourceId)

Initialize TrustKit with the Network Security Configuration file with the specified resource ID. The Network Security Configuration file must also have been added to the App's manifest.

Parameters:

context - the application's context.

configurationResourceId - the resource ID for the Network Security Configuration file to use.

Throws:

com.datatheorem.android.trustkit.config.ConfigurationException - if the policy could not be parsed or contained errors.

getInstance

@NonNull
public static TrustKit getInstance()

Retrieve the initialized instance of TrustKit.

Throws:

java.lang.IllegalStateException - if TrustKit has not been initialized.

getConfiguration

@NonNull
public com.datatheorem.android.trustkit.config.TrustKitConfiguration getConfiguration()

Retrieve the current TrustKit configuration.

getSSLSocketFactory

@NonNull
public javax.net.ssl.SSLSocketFactory getSSLSocketFactory(@NonNull
                                                                   java.lang.String serverHostname)

Retrieve an SSLSSocketFactory that implements SSL pinning validation based on the current TrustKit configuration for the specified serverHostname. It can be used with most network APIs (such as HttpsUrlConnection) to add SSL pinning validation to the connections.

The SSLSocketFactory is configured for the supplied serverHostname, and will enforce this domain's pinning policy even if a redirection to a different domain occurs during the connection. Hence validation will always fail in the case of a redirection to a different domain. However, pinning validation is only meant to be used on the App's API server(s), and redirections to other domains should not happen in this scenario.

Parameters:

serverHostname - the server's hostname that the SSLSocketFactory will be used to connect to. This hostname will be used to retrieve the pinning policy from the current TrustKit configuration.

getTrustManager

@NonNull
public javax.net.ssl.X509TrustManager getTrustManager(@NonNull
                                                               java.lang.String serverHostname)

Retrieve an X509TrustManager that implements SSL pinning validation based on the current TrustKit configuration for the supplied hostname. It can be used with some network APIs that let developers supply a trust manager to customize SSL validation.

The X509TrustManager is configured for the supplied serverHostname, and will enforce this domain's pinning policy even if a redirection to a different domain occurs during the connection. Hence validation will always fail in the case of a redirection to a different domain. However, pinning validation is only meant to be used on the App's API server(s), and redirections to other domains should not happen in this scenario.

Parameters:

serverHostname - the server's hostname that the X509TrustManager will be used to connect to. This hostname will be used to retrieve the pinning policy from the current TrustKit configuration.