+

Search Tips   |   Advanced Search

Configure SSL using untrusted certificates

Making SSL work between instances of MPF Server and clients with certificates 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 we have difficulties with getting the 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 the 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.

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

A certificate can be signed (issued) by one of the many public CAs that are known by the 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.

Use 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.

Use 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 are.


Certificate types 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 - x x x
Android - x x x
Windows Phone - x x x
Blackberry - x x x


Certificate types supported by iOS

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 - x x x


Self-signed certificates versus self-signed CAs

When we 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.

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

X.509 version 1 certificates are not allowed by some mobile platforms. You must use X.509 version 3 certificates instead. If we 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, we 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.

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


Establishing trust on the client

When we open a web page on the mobile browser or connect directly to the 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 the 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 the server.

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

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

For iOS, see Install the root CA on iOS.

For Android, see Install the root CA on Android.

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


Configure Android

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

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


Handling the certificate chain

If we are using a server certificate that is not signed by itself, we 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 WAS Liberty, see Update the 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, we must follow the RFC as closely as possible. Avoid certificate extensions unless you know that all of the targeted mobile platforms can handle them as you expect.


CRL support

If the 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:

The following example shows how to inspect a certificate:


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

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:

    basicaConstraints = CA:TRUE

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

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.

  1. Ensure that you installed the server's root CA on the client device. See Establishing trust on the client.

  2. Ensure that the server sends the complete certificate chain and in the right order. See Handling the certificate chain.

The server certificate is invalid.

  1. Check the validity of the server certificate. See Tools to use to verify the server certificate.

  2. Ensure that the CRL URL is valid and reachable. See CRL support.

  3. The server certificate contains a critical certificate extension that is not recognized by the client platform. 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 Configure 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 Install the root CA on iOS.

For Android, see Install the root CA on Android.


Parent topic: Configure MobileFirst Server

Related tasks:

Configure SSL for Liberty profile

Related information:

Security with HTTPS and SSL
HTTPS Server Trust Evaluation
The Transport Layer Security (TLS) Protocol Version 1.2
RFC 5280 - Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile