How to enable App Transport Security for iOS 9 in IBM MobileFirst Platform Server

App Transport Security is one of the new features enforced by Apple to improve secure communications between App and Web Services. This feature is available from iOS 9 or later. This post talks about how to enable transport security on IBM MobileFirst Platform Servers.

App Transport Security, in simple words, mandates the application to communicate with a web service over TLS version 1.2 protocol and use connection ciphers that provide forward secrecy. This means the developer has to ensure that the web service to which his application is communicating is deployed on a web server that supports TLS version 1.2 and forward secrecy. For more information, see Apple's Technote on App Transport Security

As of today, if the web server is not ready, the developer can override this default behavior and turn off the transport security, which is not recommended.

More details on how to turn off transport security and server setup requirements are listed in the post, ATS and Bitcode in iOS 9.

The post also talks about how the developer can switch off the transport security using the NSAllowsArbitraryLoads exception property, so that the application can communicate with the server in the development environment. The development server in the IBM MobileFirst Platform Studio eclipse and the Command Line Interface (CLI) do not support App Transport Security.

Requirements

This post shows how to set up transport security in test and production environments. Reiterating the requirements,

• The server must support communication over TLS version 1.2.
• Connection ciphers must provide forward secrecy (accepted ciphers are listed in this technote).
• SSL Certificates must be signed using a SHA256 or better algorithm.
• SSL Certificates must be signed using either a greater2048 bit or greater RSA key, or a 256 bit or greater Elliptic-Curve key.

Java

Although the settings are made on the web server to enable App Transport Security, Java is the underlying technology which should support this communication. The supported editions are:

• IBM SDK, Java Technology Edition 8.0
• IBM SDK, Java Technology Edition 7.0
• IBM SDK, Java Technology Edition 6.0
• Oracle JDK 8.0
• Oracle JDK 7.0

The listed Java SDKs will work as is for most of the ciphers that are accepted by iOS 9 for transport security. Ciphers TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384, TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 and TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 require SDK JCE policy settings.

The policy files for IBM JDKs can be downloaded here. There are two files, US_export_policy.jar and local_policy.jar. The developer can use the policy files in either of the following ways:

• Take a backup of the policy files from JDKInstalledDirectory/jre/lib/security. Replace them with the new policy files downloaded. Start the server to use the above mentioned ciphers. (Not recommended)
• Place the downloaded policy files in a location accessible to the JDK. Add the below JVM option to the server’s jvm.options.
  -Dcom.ibm.security.jurisdictionPolicyDir=PolicyFileDirectoryLocation

Note: The listed policy settings are not required if developer chooses to use any of the other accepted ciphers other than the ones mentioned above.

For the similar policy files of Oracle JDK, go to Oracle Technology Network Downloads page here and search for Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files

Certain countries restrict certain cryptography under their jurisdiction. Hence, it is the responsibility of the user to ensure proper adherence to the law.

Web Server

The Web Servers listed in the IBM MobileFirst Platform requirements page will work with the JDKs listed in this blog.

Server setup details

Ensure that the generated certificates as per requirements are ready. The following ssl_cert.p12 is the keystore that has the personal certificate and ca.crt is the signing certificate.

IBM WebSphere Liberty and Tomcat

Add the below lines to the server.xml file.

1
2
3
4
5
6
7
8
    <featureManager>
        ... ...
        <feature>ssl-1.0</feature>
        ...
        ...
    </featureManager>
    <ssl id="defaultSSLConfig" sslProtocol="TLSv1.2" keyStoreRef="defaultKeyStore" enabledCiphers="TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384" />
    <keyStore id="defaultKeyStore" location="/root/Certs/ssl_cert.p12" password="*****" type="PKCS12"/>

• The ssl-1.0 added as a feature in the feature manager enables the server to work with SSL communication
• In the ssl tag add sslProtocol="TLSv1.2". This will mandate that the server communicates only on TLS version 1.2 protocol. More than one protocol can be added like: sslProtocol="TLSv1+TLSv1.1+TLSv1.2". This ensures server can communicate on all 3 versions of TLS. So when iOS 9 application tries to communicate over TLS version 1.2, the server accepts.
• In the ssl tag add enabledCiphers="TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384". This tells the server to enforce communication using only that cipher. More ciphers can be added to the list. So when iOS 9 application tries to communicate over any of the 11 accepted ciphers, the server will communicate with the accepted cipher as long as it is in the list.
• The keyStore tag points the server to use the new certificates which are as per the above requirements.

IBM MobileFirst Platform versions 6.2 and 6.3 do not work if the server is forced to work with TLS version 1.2. Set sslProtocol to SSL_TLSv2. This protocol name is an alias and will work for SSLv3 and all 3 versions of TLS.

WebSphere Application Server

Create a WebSphere Application Profile with Security enabled. Open WAS admin console -> Security -> SSL certificate and key management -> SSL configurations.

Open NodeDefaultSSLSettings -> Key stores and certificates.

Open NodeDefaultKeyStore -> Personal certificates and import the new certificate. Point to the ssl_cert.p12 and chose to import the certificate.

Open NodeDefaultTrustStore -> Signer certificates and add the new certificate's signer certificate. Add the ca.crt as root1.

Open NodeDefaultSSLSettings -> Quality of protection (QoP) settings. Choose Protocol as SSL_TLSv2. Choose Cipher suite groups as Custom and click on Update selected ciphers button. Use the Add and Remove button to make sure accepted ciphers are in the selected ciphers list. Apply the settings.

WebSphere Application Server's own services require other versions protocol for communication. Enforcing the server to work with only TLS version 1.2 will interfere with stopping and starting the server.

Note: The string "SSL" is interchangeable with "TLS" and vice versa in the cipher names. For example, where SSL_RSA_WITH_AES_128_CBC_SHA is specified, TLS_RSA_WITH_AES_128_CBC_SHA also applies.

Save all the settings. Open the ssl.client.props file. The file will be at WASServerProfileDirectory/properties/ssl.client.props. Uncomment the property com.ibm.ssl.enabledCipherSuites=SSL_ECDHE_RSA_WITH_AES_128_CBC_SHA and set it to one of the ciphers from the selected ciphers list.

Restart the server.

IBM HTTP Server

In case the production environment has a HTTP server front ending, the App Transport Security configuration is required only on the HTTP server. At the HTTP server end point, the SSL can be offloaded. The App Transport Security needs to be configured only to the end point to which the iOS 9 application will connect. All communication beyond this end point can be unsecure or normal SSL as before.

IBM HTTP Server provides a utility, ikeyman, short for IBM Key Management. Use this utility to create a new key database. Choose the key database type as CMS. Import the ca.crt under signer certificates. Import the personal certificate from ssl_cert.p12 into the key database and save it. Remember to choose to stash the password into a file.

Open HTTPServerInstalledDirectory/conf/httpd.conf file to configure SSL.

1
2
3
4
5
6
7
LoadModule ibm_ssl_module modules/mod_ibm_ssl.so
Listen 443
<VirtualHost *:443>
SSLEnable
</VirtualHost>
KeyFile /opt/IBM/HTTPServer/key.kdb
SSLCipherSpec TLSv12 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA

Uncomment the Load Module to load the ibm_ssl_module as shown above.
Point the KeyFile to the new kdb file, key database file created using ikeyman.
SSLCipherSpec is set to TLSv12 and the cipher it should use. This ensures the HTTP Server communicates over TLS version 1.2 protocol using the specified cipher.

Rest of the HTTP Server's proxy configuration or load balancing can remain the same.

App Transport Security configuration does not impact applications connecting from other mobile operating systems.
Other mobile operating systems, though they do not mandate that servers have to communicate on this level of security, they will communicate with servers that are configured to App Transport Security.