Migrate applications to use Java keystores

Prior to WebSphere Application Server Version 5, the use of i5/OS *SYSTEM certificate stores (.kdb files) is supported for WebSphere applications that use the JSSE and SSL program interfaces. With Version 5, only Java keystores (.jks files) are fully supported. It is recommended that you migrate your applications to use Java keystores.

With Version 5, i5/OS *SYSTEM certificate stores can only be used by applications that are deployed within an administrative domain where global security is disabled. To continue using i5/OS *SYSTEM certificate stores with your applications, perform these steps:

Ensure that security is disabled for the administrative domain where your application is deployed. Use the WebSphere administrative console to disable global security.

Note: If you disable WebSphere security, your WebSphere resources may no longer be protected. Carefully assess your security needs before you disable security. If you decide that security must remain enabled, migrate your applications to use Java keystores.
In the java.security file for your WebSphere instance, change the Java security properties to enable use of i5/OS certificate stores. For example, to enable use of i5/OS certificate stores for an instance named myInst, change /QIBM/UserData/WebASE51/ASE/myInst/properties/java.security as follows:
1. Add Java security provider com.ibm.as400.ibmonly.net.ssl.Provider to the list of Java security providers. For example:
```
  security.provider.1=com.ibm.crypto.provider.IBMJCE
  security.provider.2=com.ibm.jsse.IBMJSSEProvider
  security.provider.3=com.ibm.security.jgss.IBMJGSSProvider
  security.provider.4=com.ibm.security.cert.IBMCertPath
  security.provider.5=com.ibm.crypto.pkcs11.provider.IBMPKCS11
  security.provider.6=com.ibm.as400.ibmonly.net.ssl.Provider
```
2. Change the properties that determine the default SSLSocketFactory and SSLServerSocketFactory provider implementations as follows:
```
  ssl.SocketFactory.provider=com.ibm.as400.ibmonly.net.ssl.SSLSocketFactoryImpl
  ssl.ServerSocketFactory.provider=
    com.ibm.as400.ibmonly.net.ssl.SSLServerSocketFactoryImpl
```
  Note: The ssl.ServerSocketFactory.provider property should be entered as one line in the java.security file.
Restart all servers within your administrative domain.

To migrate your applications to use Java keystores (.jks files), perform these steps:

Create Java keystores for your certificates. If your application uses a digital certificate to authenticate to itself to a server, use the iKeyman utility to create a Java keystore to contain the certificate. For more information, see The iKeyman utility in the Security topic.

Note: When you are working with iKeyman, you may find it convenient to map a drive to access keystores and certficate files that are located in the integrated file system of your iSeries system. Otherwise, you can copy the files to your workstation from your iSeries system (for example, by using file transfer protocol), modify them with iKeyman, and then copy the files to the iSeries system.

Typically, you use one keystore to contain the certificate authority certificates (CA or signer certificates) for your application (a trust keystore) and another keystore to contain the client or server certificate. If you have multiple applications, you use a keystore for each application (to contain the client or server certificate), and you use a single trust keystore for all of the applications.

If your application uses commercial certificate authority certificates (signer or CA certificates), you may be able to use the cacerts keystore (the default trust keystore) with your application. The integrated file system path for cacerts is /QIBM/ProdData/Java400/jdk13/lib/security/cacerts. However, in no case should you attempt to modify the cacerts keystore. Rather, you should create a private copy of the cacerts file, and then add or remove certificates. The password for cacerts is changeit. Be sure to change the password that protects your private copy of the cacerts file. Also, note that initially, all keystores created using iKeyman contain a number of commercial CA certificates.

You may create your Java keystores in any iSeries integrated file system directory. However, it may be convenient to place them in the same directory as those that are used by your WebSphere instance. This may make it easier to include them in your backup and restore procedure. WebSphere Application Server - Express provides an initial set of Java keystores that are used to secure connections between WebSphere components. These keystores are found in the etc directory of your WebSphere instance, for example, /QIBM/UserData/WebASE/ASE5/myInstance/etc.

For an example of how to create a Java keystore, see Using Java keystore files in the Security topic.
Use the Digital Certificate Manager (DCM) to export certificates from your i5/OS *SYSTEM certificate stores. Export both the client and server certificates that are used by your applications. Additionally, export the certificate authority (CA) certificates. For more information about DCM, see these topics in the iSeries Information Center:
Note: DCM uses PKCS12 format to export client and server certificates, and it uses base64 encoded format to export certificate authority certificates. These formats are compatible with iKeyman. However, you must to convert the base64 encoded data from EBCDIC to ASCII format before you use it with iKeyman. To convert the data, perform these steps:
1. On an iSeries command line, enter the Start Qshell (STRQSH) command.
2. Use the cd command to change to the directory that contains the file that is used to export the CA certificate.
3. Use the touch and cat commands to copy the data to another file and convert it to ASCII formate. For example, to convert the data for file myCA to file myCA.arm, enter this command:
```
  touch -C 819 myCA.arm; cat myCA > myCA.arm
```
To import certificates into your Java keystores, perform these steps:
1. Start iKeyman on your workstation. For more information, see The iKeyman utility in the Security topic.
2. Open your key database file (Java keystore):
  1. Select Open from the Key Database File menu.
  2. Click Browse... and select the file containing your key database (keystore).
  3. Click OK on the Open panel.
  Note: You may use separate keystores to contain your client or server certificates vs your CA certificates.
3. Import the client or server certificate:
  1. Select Personal Certificates from the Key database content pulldown menu.
  2. Click Export/Import...
  3. Select Import Key for the Action Type.
  4. Select PKCS12 for the Key file type.
  5. Click Browse... and select the file that contains the certificate to be imported.
  6. Click OK on the Export/Import Key panel.
4. Add signer certificates:
  1. Select Signer Certificates from the Key Database File menu.
  2. Click Add...
  3. Click Browse... and select the file that contains the signer certificate to be added.
  4. Click OK on the Add CA's certificate from a file panel.
5. Select Exit from the Key Database File menu.
Grant Read and Execute (*RX) authority to your Java keystores for the i5/OS user profile under which your application runs. For example, enter the Change Authority (CHGAUT) command to grant *RX authority to the QEJBSVR user profile for the myKeys.jks (where myKeys.jks is accessed by a servlet that is deployed on your default instance):
```
  CHGAUT OBJ('/QIBM/UserData/WebASE/ASE5/instance/etc/myKeys.jks')
   USER(QEJBSVR) DTAAUT(*RX)
```
Make the code changes that are required for using your Java keystores. The changes that are required for your applications to use your Java keystores vary, depending on your implementation. See Using Java keystore files in the Security topic for code examples.
Test your applications.
After you are convinced that your applications are working correctly, you may want to clean up files, authorities, and properties that your application no longer needs.

Note: This cleanup applies to both stand-alone Java client applications and to applications that are deployed on your application server.

One or more of the following properties may be set and should be removed from your application's runtime environment. If the application is running on your application server, the properties are set as custom properties in the runtime configuration of your application server:
- os400.certificateContainer
  If your application used the os400.certificateContainer property, also delete the certificate container (.kdb file), but only if it is no longer used by any other application.
- os400.certificateLabel
- os400.secureApplication
  If your application used the os400.secureApplication property, also use Digital Certificate Manager (DCM) to delete the secure application from the *SYSTEM certificate store.
Use Operations Navigator to remove authority to the *SYSTEM certificate store for the i5/OS user profile under which your server or client application runs. The user profile that you use to run Operations Navigator must have *SECADM special authority to perform this task.

Note: This step applies only if your application previously used certificates that were contained in the *SYSTEM certificate store, and the user profile does not require access to the *SYSTEM certificate store for any other application.

For example, if the user profile the application runs under is QEJBSVR, perform these tasks:
1. Start Operations Navigator.
2. Click the iSeries system that contains the secure client application.
3. Click Configure Application Administration in the bottom window.
4. Click the Host Applications tab.
5. Expand Digital Certificate Manager.
6. Select *SYSTEM certificate store.
7. Click Customize.
8. If Default access is selected or if QEJBSVR is not in the Access allowed list, then stop and cancel out of the tasks. You do not need to customize access.
9. Select QEJBSVR from the Access allowed panel.
10. Click Remove to remove QEJBSVR from the Access allowed panel.
11. Click OK.