Using a private certificate for SSL

You manage the certificates that your applications use for SSL sessions from the *SYSTEM certificate store in Digital Certificate Manager (DCM). If you have never used DCM on the target system to manage certificates for SSL, then this certificate store will not exist on the target system.

The tasks for using the transferred certificate store files that you created on the local Certificate Authority (CA) host system vary based on whether the *SYSTEM certificate store exists. If the *SYSTEM certificate store does not exist, you can use the transferred certificate files as a means of creating the *SYSTEM certificate store. If the *SYSTEM certificate store does exist on the target system, you can either use the transferred files as an Other System Certificate Store or import the transferred files into the existing *SYSTEM certificate store.

*SYSTEM certificate store does not exist

If the *SYSTEM certificate store does not exist on the system on which you want to use the transferred certificate store files, you can use the transferred certificate files as the *SYSTEM certificate store. To create the *SYSTEM certificate store and use the certificate files on your target system, follow these steps:
  1. Make sure that the certificate store files (two files: one with a .KDB extension and one with a .RDB extension) that you created on the system that hosts the local CA are in the /QIBM/USERDATA/ICSS/CERT/SERVER directory.
  2. Once the transferred certificate files are in the /QIBM/USERDATA/ICSS/CERT/SERVER directory, rename these files to DEFAULT.KDB, and DEFAULT.RDB.
    By renaming these files in the appropriate directory, you create the components that comprise the *SYSTEM certificate store for the target system. The certificate store files already contain copies of certificates for many public Internet CAs. DCM added these, as well as a copy of the local CA certificate, to the certificate store files when you created the them.
    Attention: If your target system already has a DEFAULT.KDB and a DEFAULT.RDB file in the /QIBM/USERDATA/ICSS/CERT/SERVER directory, the *SYSTEM certificate store currently exists on this target system. Consequently, you must not rename the transferred files as suggested. Overwriting the default files will create problems when using DCM, the transferred certificate store, and its contents. Instead, you must ensure that they have unique names and must use the transferred certificate store as an Other System Certificate Store. If you use the files as an Other System Certificate Store, you cannot use DCM to specify which applications will use the certificate.
  3. Start DCM. You must now change the password for the *SYSTEM certificate store that you created by renaming the transferred files. Changing the password allows DCM to store the new password so that you can use all DCM certificate management functions on the certificate store.
  4. In the navigation frame, click Select a Certificate Store and select *SYSTEM as the certificate store to open.
  5. When the Certificate Store and Password page displays, provide the password that you specified on the host system for the certificate store when you created the certificate for the target system and click Continue.
  6. In the navigation frame, select Manage Certificate Store and select Change password from the list of tasks. Complete the form to change the password for the certificate store. After you change the password, you must re-open the certificate store before you can work with the certificates in it. Next you can specify which applications will use the certificate for SSL sessions.
  7. In the navigation frame, click Select a Certificate Store and select *SYSTEM as the certificate store to open.
  8. When the Certificate Store and Password page displays, provide the new password and click Continue.
  9. After the navigation frame refreshes, select Manage Certificates in the navigation frame to display a list of tasks.
  10. From the task list, select Assign certificate to display a list of certificates in the current certificate store.
  11. Select the certificate that you created on the host system and click Assign to Applications to display a list of SSL-enabled applications to which you can assign the certificate.
  12. Select the applications that will use the certificate for SSL sessions and click Continue.
    DCM displays a message to confirm your certificate selection for the applications.
    Note: Some SSL-enabled applications support client authentication that is based on certificates. An application with this support might want to more narrowly define the CA certificates that it trusts from the list of enabled CA certificates in the *SYSTEM certificate store. To do this configuration, you must define a CA trust list for the application and select enabled CAs from the *SYSTEM store to trust. If a CA trust list is not defined, all enabled CA certificates in the *SYSTEM certificate store are trusted.

With these tasks complete, applications on the target system can use the certificate issued by the local CA on another system. However, before you can begin using SSL for these applications, you must configure the applications to use SSL.

Before a user can access the selected applications through an SSL connection, the user must use DCM to obtain a copy of the local CA certificate from the host system. The local CA certificate must be copied to a file on the user's PC or downloaded into the user's browser, depending on the requirements of the SSL-enabled application.

*SYSTEM certificate store exists — using the files as an Other System Certificate

If the target system already has a *SYSTEM certificate store, you must decide how to work with the certificate files that you transferred to the target system. You can choose to use the transferred certificate files as an Other System Certificate Store. Or, you can choose to import the private certificate and its corresponding local CA certificate into the existing *SYSTEM certificate store.

Other System Certificate Stores are user-defined secondary certificate stores for SSL certificates. You can create and use them to provide certificates for user-written SSL-enabled applications that do not use DCM APIs to register an application ID with the DCM feature. The Other System Certificate Store option allows you to manage certificates for applications that you or others write that use the SSL_Init API to programmatically access and use a certificate to establish an SSL session. This API allows an application to use the default certificate for a certificate store rather than a certificate that you specifically identify.

IBM i applications (and many other software developers' applications) are written to use certificates in the *SYSTEM certificate store only. If you choose to use the transferred files as an Other System Certificate Store, you cannot use DCM to specify which applications will use the certificate for SSL sessions. Consequently, you cannot configure standard IBM i SSL-enabled applications to use this certificate. If you want to use the certificate for IBM i applications, you must import the certificate from your transferred certificate store files into the *SYSTEM certificate store.

To access and work with the transferred certificate files as an Other System Certificate Store, follow these steps:

  1. Start DCM.
  2. In the navigation frame, click Select a Certificate Store and select Other System Certificate Store as the certificate store to open
  3. When the Certificate Store and Password page displays, provide the fully qualified path and file name of the certificate store file (the one with the .KDB extension) that you transferred from the host system.
    Also provide the password that you specified on the host system for the certificate store when you created the certificate for the target system and click Continue.
  4. In the navigation frame, select Manage Certificate Store and select Change password from the list of tasks.
    Complete the form to change the password for the certificate store.
    Note: Be sure to select the Automatic login option when you change the password for the certificate store. Using this option ensures that DCM stores the new password so that you can use all DCM certificate management functions on the new store.
    After you change the password, you must re-open the certificate store before you can work with the certificates in it. Next you can specify that the certificate in this store be used as the default certificate
  5. In the navigation frame, click Select a Certificate Store and select Other System Certificate Store as the certificate store to open.
  6. When the Certificate Store and Password page displays, provide the fully qualified path and file name of the certificate store file, provide the new password, and click Continue.
  7. After the navigation frame refreshes, select Manage Certificate Store and select Set default certificate from the list of tasks.

Now that you have created and configured the Other System Certificate store, any applications that use the SSL_Init API can use the certificate in it to establish SSL sessions.

*SYSTEM certificate store exists — using the certificates in the existing *SYSTEM certificate store

You can use the certificates in the transferred certificate store files in an existing *SYSTEM certificate store on a system. To do so, you must import the certificates from the certificate store files into the existing *SYSTEM certificate store. However, you cannot import the certificates directly from the .KDB and .RDB files because they are not in a format that the DCM import function can recognize and use. To use the transferred certificates in an existing *SYSTEM certificate store, you must open the files as an Other System Certificate Store and export them into the *SYSTEM certificate store.

To export the certificates from the certificate store files into the *SYSTEM certificate store, complete these steps on the target system:

  1. Start DCM.
  2. In the navigation frame, click Select a Certificate Store and specify Other System Certificate Store as the certificate store to open.
  3. When the Certificate Store and Password page displays, provide the fully qualified path and file name of the certificate store file (the one with the .KDB extension) that you transferred from the host system.
    Also provide the password that you specified on the host system for the certificate store when you created the certificate for the target system and click Continue.
  4. In the navigation frame, select Manage Certificate Store and select Change password from the list of tasks.
    Complete the form to change the password for the certificate store. After you change the password, you must re-open the certificate store before you can work with the certificates in it.
    Note: Be sure to select the Automatic login option when you change the password for the certificate store. Using this option ensures that DCM stores the new password so that you can use all DCM certificate management functions on the new store. If you do not change the password and select the Automatic login option, you may encounter errors when exporting the certificates from this store into the *SYSTEM certificate store.
  5. In the navigation frame, click Select a Certificate Store and select Other System Certificate Store as the certificate store to open.
  6. When the Certificate Store and Password page displays, provide the fully qualified path and file name of the certificate store file, provide the new password, and click Continue.
  7. After the navigation frame refreshes, select Manage Certificates in the navigation frame to display a list of tasks and select Export certificate.
  8. Select Certificate Authority (CA) as the type of certificate to export and click Continue.
    Note: You must export the local CA certificate into the certificate store before you export the server or client certificate into the certificate store. If you export the server or client certificate first, you may encounter an error because the local CA certificate does not exist in the certificate store.
  9. Select the local CA certificate to export and click Export.
  10. Select Certificate store as the destination for the exported certificate and click Continue.
  11. Enter *SYSTEM as the target certificate store, enter the password for the *SYSTEM certificate store, and click Continue.
    A message displays to indicate that the certificate exported successfully or to provide error information if the export process failed.
  12. Now you can export the server or client certificate into the *SYSTEM certificate store. Re-select the Export certificate task.
  13. Select Server or client as the type of certificate to export and click Continue.
  14. Select the appropriate server or client certificate to export and click Export.
  15. Select Certificate store as the destination for the exported certificate and click Continue.
  16. Enter *SYSTEM as the target certificate store, enter the password for the *SYSTEM certificate store, and click Continue.
    A message displays to indicate that the certificate exported successfully or to provide error information if the export process failed.
  17. Now you can assign the certificate to applications to use for SSL. Click Select a Certificate Store in the navigation frame and select *SYSTEM as the certificate store to open.
  18. When the Certificate Store and Password page displays, provide the password for the *SYSTEM certificate store and click Continue.
  19. After the navigation frame refreshes, select Manage Certificates to display a list of tasks.
  20. From the task list, select Assign certificate to display a list of certificates in the current certificate store.
  21. Select the certificate that you created on the host system and click Assign to Applications to display a list of SSL-enabled applications to which you can assign the certificate.
  22. Select the applications that will use the certificate for SSL sessions and click Continue. DCM displays a message to confirm your certificate selection for the applications.
    Note: Some SSL-enabled applications support client authentication that is based on certificates. An application with this support might want to more narrowly define the CA certificates that it trusts from the list of enabled CA certificates in the *SYSTEM certificate store. To do this configuration, you must define a CA trust list for the application and select enabled CAs from the *SYSTEM store to trust. If a CA trust list is not defined, all enabled CA certificates in the *SYSTEM certificate store are trusted.

With these tasks complete, applications on the target system can use the certificate issued by the local CA on another system. However, before you can begin using SSL for these applications, you must configure the applications to use SSL.

Before a user can access the selected applications through an SSL connection, the user must use DCM to obtain a copy of the local CA certificate from the host system. The local CA certificate must be copied to a file on the user's PC or downloaded into the user's browser, depending on the requirements of the SSL-enabled application.