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.
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.
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.
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.
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"/>
ssl-1.0added as a feature in the feature manager enables the server to work with SSL communication
- In the
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
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.
keyStoretag 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.
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.
Inclusive terminology note: The Mobile First Platform team is making changes to support the IBM® initiative to replace racially biased and other discriminatory language in our code and content with more inclusive language. While IBM values the use of inclusive language, terms that are outside of IBM's direct influence are sometimes required for the sake of maintaining user understanding. As other industry leaders join IBM in embracing the use of inclusive language, IBM will continue to update the documentation to reflect those changes.