Certificate pinning

Use certificate pinning to help prevent man-in-the-middle attacks.

When communicating over public networks it is essential to send and receive information securely. The protocol widely used to secure these communications is SSL/TLS. (SSL/TLS refers to Secure Sockets Layer or to its successor, TLS, or Transport Layer Security.) SSL/TLS uses digital certificates to provide authentication and encryption. To trust that a certificate is genuine and valid, it is digitally signed by a root certificate belonging to a trusted certificate authority (CA). Operating systems and browsers maintain lists of trusted CA root certificates so that they can easily verify certificates that the CAs have issued and signed.

Protocols that rely on certificate chain verification, such as SSL/TLS, are vulnerable to a number of dangerous attacks, including man-in-the-middle attacks, which occur when an unauthorized party is able to view and modify all traffic passing between the mobile device and the backend systems.

IBM MobileFirst™ Platform Foundation provides an API to enable certificate pinning. It is supported in native iOS, native Android, and hybrid iOS or hybrid Android MobileFirst applications.

Certificate pinning process

Certificate pinning is the process of associating a host with its expected public key. Because you own both the server-side code and the client-side code, you can configure your client code to accept only a specific certificate for your domain name, instead of any certificate that corresponds to a trusted CA root certificate recognized by the operating system or browser.

A copy of the certificate is placed in your client application. During the SSL handshake (first request to the server), the IBM MobileFirst Platform Foundation client SDK verifies that the public key of the server certificate matches the public key of the certificate that is stored in the app.

Important:

Some mobile operating systems might cache the certificate validation check result. Therefore, your code should call the certificate pinning API before making a secured request. Otherwise, any subsequent request might skip the certificate validation and pinning check.
Make sure to use only MobileFirst APIs for all communications with the related host, even after the certificate pinning. Using third-party APIs to interact with the same host might lead to unexpected behavior, such as caching of a non-verified certificate by the mobile operating system.
Calling this method a second time overrides the previous pinning operation.

If pinning is successful, the public key inside the provided certificate is used to verify the integrity of the MobileFirst Server certificate during the secured request SSL/TLS handshake. If pinning fails, all SSL/TLS requests to the server are rejected by the client application.

Certificate setup

You must use a certificate purchased from a certificate authority. Self-signed certificates are not supported. For compatibility with the supported environments, make sure to use a certificate that is encoded in DER (Distinguished Encoding Rules, as defined in the International Telecommunications Union X.690 standard) format.

You must place the certificate in both the MobileFirst Server and in your application. Place the certificate as follows:

In the MobileFirst Server: (WebSphere® Application Server, WebSphere Application Server Liberty, or Apache Tomcat). Consult the documentation for your specific application server for information about how to configure SSL/TLS and certificates.
In your application:
- Native iOS: add the certificate to the application bundle
- Native Android: place the certificate in the assets folder
- Hybrid: place the certificate in the project-name\apps\app-name\certificates folder

Certificate pinning API

Certificate pinning consists of a single API method, that has a parameter certificateFilename, where certificateFilename is the name of the certificate file.

Native Android

Syntax:

public void pinTrustedCertificatePublicKey(String certificateFilename) throws IllegalArgumentException

Example:

WLClient.getInstance().pinTrustedCertificatePublicKey("myCertificate.cer");

The certificate pinning method will throw an exception in two cases:

The file does not exist
The file is in the wrong format

Native iOS

Syntax:

pinTrustedCertificatePublicKeyFromFile:(NSString*) certificateFilename;

Example:

[[WLClient sharedInstance]pinTrustedCertificatePublicKeyFromFile:@"myCertificate.cer"];

The certificate pinning method will raise an exception in two cases:

The file does not exist
The file is in the wrong format

Hybrid

Syntax:

WL.Client.pinTrustedCertificatePublicKey(certificateFilename.then(onSuccess,onFailure)

The certificate pinning method returns a promise:

The certificate pinning method will call the onSuccess method in case of successful pinning.
The certificate pinning method will trigger the onFailure callback in two cases:
- The file does not exist
- The file is in the wrong format

Example:

WL.Client.pinTrustedCertificatePublicKey('myCertificate.cer').then(onSuccess,onFailure)

Later, if a secured request is made to a server whose certificate is not pinned, the onFailure callback of the specific request (for example, WL.Client.connect or WLResourceRequest) is called.

Note: Certificate pinning is not supported for Cordova applications.

For more details on the certificate pinning API, see the following reference sections:

Native Android: Java™ client-side API WLClient class.
Native iOS: Objective-C client-side API WLClient class.
Hybrid: JavaScript client-side API WL.Client class.