Configuring SSL by using untrusted certificates

Making SSL work between instances of IBM MobileFirst™ Platform Server and clients with certificates that are not signed by a known public certificate authority (CA) can be challenging. Each mobile platform has its own peculiarities and enforces different portions of the transport layer security (TLS) standard at different times.

The following recommendations focus mostly on the iOS and Android environments. Support for X.509 certificates comes from the individual platforms, not from IBM MobileFirst Platform Foundation. For more information about specific requirements for X.509 certificates, see the documentation of each mobile platform.

If you have difficulties with getting your application to access a MobileFirst Server because of SSL-related issues, the likely cause is a bad server certificate. Another likely cause is a client that is not properly configured to trust your server. Many other reasons can cause an SSL handshake to fail, so not all possibilities are covered. Some hints and tips are provided to troubleshoot the most basic issues that are sometimes forgotten or overlooked. These issues are important when you deal with the mobile world and X.509 certificates.

Basic concepts

Certificate authority (CA)

An entity that issues certificates. A CA can issue (sign) other certificates or other CA certificates (intermediate CA certificates).

In a public key infrastructure (PKI), certificates are verified by a hierarchical chain of trust. The topmost certificate in this tree is the root CA certificate.

You can purchase your certificates from a public Internet CA or operate your own private (local) CA to issue private certificates for your users and applications. A CA is meant to be an authority that is well-trusted by your clients. Most commercial CAs issue certificates that are automatically trusted by most web browsers and mobile platforms. Using private CAs means that you must take certain actions to ensure that the client trusts certificates that are signed by your root CA.

A certificate can be signed (issued) by one of the many public CAs that are known by your mobile platforms, a private CA, or by itself.

Self-signed certificate

A certificate that is signed by itself and has no CA that attests to its validity.

Using self-signed certificates is not recommended because most mobile platforms do not support their use.

Self-signed CA

A CA that is signed by itself. It is both a certificate and a CA. Because it is the topmost certificate in a tree, it is also the root CA.

Using certificates that are signed by private CAs is not recommended for production use on external Internet-facing servers because of security concerns. However, they might be the preferred option for development and testing environments due to their low cost. They are also often appropriate for internal (intranet) servers as they can be deployed quickly and easily.

Certificate types that are supported by different mobile platforms

Table 1. Certificate types that are supported by different mobile platforms
Platform	self-signed certificates	self-signed CA certificates	certificates that are signed by a private CA	certificates that are signed by a public CA
iOS	-	✔	✔	✔
Android	-	✔	✔	✔
Windows Phone	-	✔	✔	✔
Blackberry	-	✔	✔	✔
Windows 8	-	✔	✔	✔

Self-signed certificates versus self-signed CAs

When you are dealing with mobile clients, the use of self-signed certificates is not recommended because mobile platforms do not allow the installation of these types of certificates onto the device truststore. This restriction makes it impossible for the client to ever trust the server’s certificate. Although self-signed certificates are often recommended for development and testing purposes, they will not work when the client is a mobile device.

The alternative is to use self-signed CA certificates instead of self-signed certificates. Self-signed CA certificates are as easy to acquire and are also as cost-effective of a solution.

You can create a self-signed CA with most tools. For example, the following command uses the openssl tool to create a self-signed CA:

openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout privateKey.key -out certificate.crt -reqexts v3_req -extensions v3_ca

Note: X.509 version 1 certificates are not allowed by some mobile platforms. You must use X.509 version 3 certificates instead. If you are generating self-signed CA certificates, ensure that they are of the type X.509 version 3, and have the following extension defined: basicConstraints = CA:TRUE. See the appropriate tool’s documentation for how to specify the required version and certificate extensions. For openssl commands, you can specify the -reqexts v3_req flag to indicate version 3 X.509 certificates, and the -extensions v3_ca flag to indicate that the certificate is also a CA.

You can check the certificate version and extensions by running the following openssl command:

openssl x509 -in certificate.crt -text -noout

Establishing trust on the client

When you open a web page on your mobile browser or connect directly to your MobileFirst Server on an HTTPS port, a client receives a server certificate in the SSL handshake. The client then evaluates the server certificate against its list of known and trusted CAs to establish trust. Each mobile platform includes a set of trusted CAs that are deemed trustworthy for issuing SSL certificates. Trust is established if your server certificate is signed by a CA that is already trusted by the device. After trust is established, the SSL handshake is successful and you are allowed to open the web page on a browser or connect directly to your server.

However, if your server uses a certificate that is signed by a CA that is unknown to the client, the trust cannot be established, and your SSL handshake fails. To ensure your client device trusts your server’s certificate, you must install the trust anchor certificate (root CA) on the client device.

Note: Only the root CA certificate (trust anchor) needs to be installed. You do not need to install any other certificates, such as intermediaries, on the device.

For iOS, see Installing the root CA on iOS.

For Android, see Installing the root CA on Android.

For Windows Phone, see Installing the root CA on Windows Phone.

For Windows 8, see Installing the root CA on Windows 8.

Configuring Android

It is important to note that if the following flag is set to true in your application, Android ignores SSL errors under certain conditions:

android:debuggable="true"

The use of this flag is highly discouraged for production environments. It is not necessary if you properly configured your server with a certificate that is signed by a CA that is trusted by your client device.

Handling the certificate chain

If you are using a server certificate that is not signed by itself, you must ensure that the server sends the full certificate chain to the client.

For the client to validate the certificate path, it must have access to the full certificate chain. To ensure that the client has access to the full certificate chain, including intermediate certificates, ensure that all the certificates in the chain are in the server-side keystore file.

For the WebSphere® Application Server Liberty, see Updating your keystore and Liberty profile configuration to use a certificate chain.

Handling certificate extensions

RFC 5280 (and its predecessors) defines a number of certificate extensions that provide extra information about the certificate. Certificate extensions provide a means of expanding the original X.509 certificate information standards.

When an extension is specified in an X.509 certificate, the extension must specify whether it is a critical or non-critical extension. A client that is processing a certificate with a critical extension that the client does not recognize, or which the client cannot process, must reject the certificate. A non-critical extension can be ignored if it is not recognized.

Not all mobile platforms recognize or process certain certificate extensions in the same manner. For this reason, you must follow the RFC as closely as possible. Avoid certificate extensions unless you know that all of your targeted mobile platforms can handle them as you expect.

CRL support

If your certificate supports certificate revocation lists (CRLs), ensure that the CRL URL is valid and accessible. Otherwise, certificate chain validation fails.

Tools to use to verify the server certificate

To debug certificate path validation problems, try the openssl s_client command line tool. This tool generates good diagnostic information that is helpful in debugging SSL issues.

The following example shows how to use the openssl s_client command line tool:

openssl s_client -CApath $HOME/CAdir -connect hostname:port

The following example shows how to inspect a certificate:

openssl x509 -in certificate.crt -text -noout

Troubleshooting problems with server certificates that are not signed by a trusted certificate authority

Table 2. Troubleshoot problems with server certificates
Problem	Actions to take
Unable to install the root CA on iOS. Certificate installs, but after installation, iOS shows the certificate as not trusted.	The certificate is not identified as a certificate authority. Ensure that the certificate specifies a certificate extension: `basicConstraints = CA:TRUE` For more information, see Self-signed certificates versus self-signed CAs. Ensure that the certificate is in `PEM` format. Ensure that the certificate has a .crt file extension.
Unable to install the root CA on Android. After installation, the certificate does not show up in the system trusted credentials.	The certificate is an X.509 version 1 certificate or does not have the following certificate extension: `basicConstraints = CA:TRUE` For more information, see Self-signed certificates versus self-signed CAs. Ensure that the certificate is in `PEM` or `DER` format. Ensure that the certificate has a .crt file extension.
`"errorCode":"UNRESPONSIVE_HOST","errorMsg":"The service is currently not available."`	This error usually indicates an SSL handshake failure. The client cannot establish trust for the server certificate. Ensure that you installed the server’s root CA on the client device. For more information, see Establishing trust on the client. Ensure that the server sends the complete certificate chain and in the right order. For more information, see Handling the certificate chain. The server certificate is invalid. Check the validity of the server certificate. For more information, see Tools to use to verify the server certificate. Ensure that the CRL URL is valid and reachable. For more information, see CRL support. The server certificate contains a critical certificate extension that is not recognized by the client platform. For more information, see Handling certificate extensions.
SSL works on Android, but does not work on iOS.	When Android is in `debuggable` mode, Cordova ignores most SSL errors. This behavior gives the impression that things are working. Android is in `debuggable` mode when the APK is unsigned, or when you explicitly set the mode in the manifest. Verify that the `debuggable` flag is set to `false` (`debuggable:false`) in the Android manifest file, or sign the APK. Make sure that there is no explicit declaration in the manifest that sets it to `debuggable` mode. For more information about configuring Android, see Configuring Android.
After installation, the certificate does not show up in the system’s trusted credentials or truststore.	Ensure that you did not install the server certificate by accessing the protected resource directly from your browser. This action imports the certificate only into the browser space and not into the device system truststore. The only requirement is that you install the root CA. For more information about how to properly install the root CA on the device, see the following topics. For iOS, see Installing the root CA on iOS. For Android, see Installing the root CA on Android.
`SCRIPT7002: XMLHttpRequest: Network Error 0x2ee4, Could not complete the operation due to error 00002ee4`	Ensure that you installed the server's root CA on the client device. For more information, see Establishing trust on the client. Ensure that the server sends the complete certificate chain and in the right order. For more information, see Handling the certificate chain.