IBM Support

How to configure Maximo Mobile with SSL?

Technical Blog Post


Abstract

How to configure Maximo Mobile with SSL?

Body

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.
 
Note: Out of the box, the password to access the cacerts in both JRE and Mobile J9 is changeit
Note 1: Commands from the J9 SDK (maximo_root\mobiletools\tools\wece-win-x86\bin)
Note 2: Assumes that both the cacerts and the .cer file are under c:\clients\test\ 
Note 3: The folder names and paths will be different for the clients.You need to use the appropriate ones

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 
 
Note: -alias - You can use anything you want as long as it is not in use already to check what is in use the command
Note 1: -file    - This is the path to the certificate to be added to the cacert
Note 2: -keystore this is the path to the cacert file
Note 3:  In case you are asked if you trust in the certificate, answer yes.

How to list the certificates of a keystore?
 
keytool -list -keystore c:\clients\test\cacerts
 
To conclude, there are some important closing notes:  
  1. Suppose you added your custom certificate to the desktop JVM and it started to work fine. You added the same certificate to the handheld JVM but will still get an error to connect to the hosting server. This is not common, but sometimes it happens. The reason for this inconvenience is caused because the cacerts file of the Desktop JVM has more certificates in its out of the box distribution than the handheld's one. The result is the chain to your custom certificate is not complete. To solve this, you need to find out what is (or are) the missing certificate(s). The fastest approach is to export all the certificates from the Desktop cacerts and import them on the handheld cacerts.
  2. Your certificate might expire and the JVM will not be able to perform HTTPS requests to your server. In that case, when you have the new certificate, just import it to the cacerts overriding the expired certificate.
  3. You can get more details about errors on the handheld enabling logs or lauching the application in debug mode. More information in this link.
  4. Do not try to use the JDK keystore to manage the handheld keystore. The handheld keystore format is not recognized by the JDK keytool.
  5. Do not copy the desktop cacerts to the handheld. The J9 will not be able to read the file due to its format and will not launch. 
 
Hope this document helps you on the next time you need to work with SSL certificates for the Maximo Mobile product.

[{"Business Unit":{"code":"BU055","label":"Cognitive Applications"},"Product":{"code":"SSLKT6","label":"Maximo Asset Management"},"Component":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"","Edition":""}]

UID

ibm11134489