How to configure Maximo Mobile with SSL?

Maximo Mobile applications are Java based applications that run on Windows based devices, such as PDAs with Windows Mobile, and Netbooks, Notebooks and Desktops. Those applications use a HTTP channel to exchange data, like Assets, Locations, Work Orders and Tickets with Maximo EAM. The HTTP protocol by itself does not provide cryptography on the data transport. The combination of HTTP + SSL (Security Socket Layer) support the data exchange between the server that hosts Maximo EAM and the Maximo Mobile applications. This combination is widely known as HTTPS.

 

From the Maximo Mobile perpective, the basic configuration related to use HTTPS during the data exchange with the Maximo EAM is very simple. Just change the maximo.mobile.ssl property to true in the mobile.properties of your application. When that property is set to true, the requests will use the https protocol instead of http. To give a concrete example, suppose you are using the following configuration in your mobile.properties file for the Mobile Inventory Management Application:

 

maximo.mobile.hostname=mymaximo.mycompany.com

maximo.mobile.port=443

maximo.mobile.ssl=true

maximo.mobile.contextname=/maximomobile/mobileservice

 

When you try to login for the first time in the application, the following URL will be requested by the application:  https://mymaximo.mycompany.com:443/maximomobile/mobileservice

 

But if something goes wrong? If you get a message saying there was a failure trying to connect with the server that hosts Maximo EAM, where do you need to look or what you need to do?

  

The first basic thing you need to check is if your SSL certificate is correctly installed in your application server and if the port associated to receive http requests is the port you are configuring in the mobile.properties file. Another way to verify if the certificates are installed on the application server and which port is being is by trying to login into the Maximo EAM using the web browser. You need to pay attention on the URL and port the application is trying to connect. It is important to say this is not a common problem.

 

We recommend Maximo Mobile customers to perform all the applicable configurations on the desktop first before move to a handheld device because it is very straight forward to see details of errors that might happen. With that said, suppose you checked your application server and everything is fine from the SSL configurations perspective and you get an error on the DOS console from there you launch the Mobile Inventory Management application with messages like SSL handshake exception or SunCertPathBuilderException:  unable to find valid certification path to requested target

it means you need to take some additional steps in your configuration.  Let us first try to quickly understand what that means before look at the solution.

 

What happens from the Java perspective?

 

For a JVM works with SSL, it must have the customer certificate installed on the JVM's keystore (a.k.a. cacerts file). The problem is that not only the customer's certificate must be in the cacerts, but the certificate that certifies the customer's certificate. It is a bit more difficult, because we need the certificate that certifies the certificate that certifies the customer's certificate. This chain goes until a root certificate. 

If we want to use the customer SSL certificate but the keystore does not have all the certificates needed in the chain until the root, an exception is thrown. To add the certificate to the JVM keystore is a standard procedure working with Java application and SSL. You can find more information in this link or on the internet by looking for 'Java and SSL' in your favorite searcher.

 

 With all that said, the next step is to fix the problem we had. The solution is: Add the public certificate to the keystore of our JVM. The information to perform this task is presented below:

 

How do I manage the keystore? Is it the same for the mobile J9?

 

JRE (and JDK, as well) provides a tool called keytool which is used to manage the keystore. With this tool we can add, remove, export, import and list the contents of a keystore. The big issue is that there is a difference between the format of the cacerts file that  mobile J9 works with the desktop J9 and desktop JRE. In practice, it means that we cannot use the keytool of the desktop JVM to manage the keystore of the mobile J9. Because of this, Maximo Mobile Suite is shipped since version 7.5.0.0  with the appropriate keytool to manage the mobile J9 keystore. If you have Maximo Mobile 7.1.1.0, the tool is available in a hotfix package. If you have a previous version of Maximo Mobile, please contact IBM Support to get the tool.

  

When we want a Maximo Mobile application running on the desktop to connect to Maximo using SSL, the certificates must be added to the cacerts of the JVM that runs the application. The JVM can be found looking the .cmd file used to launch the application (depending on how it was configured, the setEnv.cmd is the file that points to the JVM directory). Once the directory was identified and found, the keytool can be found in the jre\bin directory and the cacerts under \jre\lib\security. On the other hand, the keystore on the handheld is placed are under folder \J9\PPRO11\lib\security. On the Maximo Mobile side, the keytool is installed in maximo_root\mobiletools\tools\wece-win-x86\bin and the keystore (a copy of the one that is installed out of the box on the handheld) can be found at maximo_root\mobiletools\tools\wece-win-x86\lib\security.

 

These are some basic instructions on how to use the keytool. The instructions below do apply for both keytools. A list of other commands can be found by issuing the keytool command without any argument.

 

How to import certificates into the cacert file for clients on using mobile devices with SSL?

 

keytool -import -alias ca-prd-01 -file C:\clients\test\ca-prd-01_Root_CA_for_Client.cer -keystore C:\clients\test\cacerts

keytool -import -alias max-app-prd01 -file C:\clients\test\Maximo-EAM-APP-PRD-01.cer -keystore C:\clients\test\cacerts 

 

How to list the certificates of a keystore?

 

keytool -list -keystore c:\clients\test\cacerts

 

To conclude, there are some important closing notes:  

 

Hope this document helps you on the next time you need to work with SSL certificates for the Maximo Mobile product.