Switching default Copy Services Manager server and client certificates

You can switch the default server and client certificates for Copy Services Manager. This manual process involves uploading the .jks files.

wlp/bin> securityUtility encode --encoding=xor passw0rd
{xor}Lz4sLChvLTs=

Encoding options:
--encoding={xor|aes|hash}
    Specify how to encode the password. Supported encodings are xor, aes,
    and hash. The default encoding is xor.

Follow these steps to switch out the default certificates and key files that are assigned by Copy Services Manager. The example uses different keystore and truststore file names to clearly differentiate the configuration from keystores and certificates. It also prevents you from overwriting the original files.

1. Create a new directory within the etc directory named csmKeyStoreBackup to back up the original keystore and truststore files. These files are at these locations:
   • path_prefix/opt/IBM/CSM/wlp/usr/servers/csmServer/etc/ for z/OS
   • install dir/liberty/wlp/usr/servers/csmServer/etc/ for distributed systems
2. Generate a new keystore file using the keytool command. For example, you can name the file myCSMKeyStore.jks (myCsmKeyStore.jks is an example file name. Replace it with your preferred file name):

   keytool -genkey -keystore {homedirectory}/etc/myCsmKeyStore.jks -keyalg RSA -alias 127.0.0.1

   Note: It is recommended to migrate to PKCS12 format after running this command. To do so, use the command shown in step 2A.
   2A. Convert the keystore file from JKS to PKCS12 format:

   keytool -importkeystore -srckeystore {homedirectory}/etc/myCsmKeyStore.jks -destkeystore {homedirectory}/etc/myCsmKeyStore.jks -deststoretype pkcs12

3. Import the newly generated keystore:

   keytool -genkey -keyalg RSA -alias csm-127.0.0.1 -keystore {homedirectory}/etc/myCsmKeyStore.jks -storepass passw0rd -validity 3600 -keysize 2048

4. Create a public certificate:

   keytool -export -keystore {homedirectory}/etc/myCsmKeyStore.jks -alias csm-127.0.0.1 -file {homedirectory}/etc/csm-127.0.0.1.arm

5. Generate a new truststore file. For example, you can name the file myCsmTrust.jks (myCsmTrust.jks is an example file name. Replace it with your preferred file name):

   keytool -genkey -keystore {homedirectory}/etc/myCsmTrust.jks -keyalg RSA -alias 127.0.0.1

6. Import the public certificate into the truststore:

   keytool -import -alias csm-127.0.0.1 -file {homedirectory}/etc/csm-127.0.0.1.arm -storetype PKCS12 -keystore {homedirectory}/etc/myCsmTrust.jks

7. Update your rmserver.properties file. This file can be found at:
   • path_prefix/opt/IBM/CSM/wlp/usr/servers/csmServer/properties for z/OS
   • install dir/liberty/wlp/usr/servers/csmServer/properties for distributed systems

   Update the file name and password for the following options:

   communications.keyStore=etc/myCsmKeyStore.jks 
   communications.keyStorePwd=<Password for myCsmKeyStore.jks>
   
   communications.authStore=etc/myCsmTrust.jks
   communications.authStorePwd=<Password for myCsmTrust.jks>

8. Update your csmConnection.properties file in the CSM client for the same:

   csm.server.keystore=etc/myCsmTrust.jks
   csm.server.certificate=csm-<servername>

9. Update the bootstrap.properties file in the CSM server directory with your new keystore and truststore files:

   com.ibm.ssl.keyStoreName=myCsmKeyStore
   com.ibm.ssl.keyStore={homedirectory}/etc/myCsmKeyStore.jks
   com.ibm.ssl.keyStorePassword=<Password for myCsmKeyStore.jks>
   
   com.ibm.ssl.trustStoreName=myCsmTrustStore
   com.ibm.ssl.trustStore={homedirectory}/etc/myCsmTrust.jks
   com.ibm.ssl.trustStorePassword=<Password for myCsmTrust.jks>

10. Restart the Copy Services Manager server and client for these changes to take effect.

The next five steps involve the command-line interface (CLI).

11. Copy your common trust file myCsmTrust.jks to the Copy Services Manager CLI directory at install dir/CLI/etc.
12. Create a properties directory in the CLI directory (install dir/CLI/properties)
13. Create a csmclient.properties file in the properties directory. This file is used to specify a custom truststore for encryption between the CLI client and the Copy Services Manager server. Add the following details in the file.

    communications.trustStore=etc/myCsmTrust.jks
    communications.trustStore.password=<assigned password>
    

    Note:

    • The default csmTrust.jks file is embedded in the csmcli.jar file. You cannot remove it. Use the csmclient.properties file to use a different truststore. The truststore file is at install dir/CLI/etc by default.
    • Certificate configuration errors in this file result in CSMCLI login not working due to invalid encryption for authenticating with the Copy Services Manager server.
14. Log on to the Copy Services Manager CLI.
15. Optional: If you have the stand-alone CLI extracted on other systems in your environment, repeat the CLI steps.
16. To establish a Copy Services Manager HA relationship to another Copy Services Manager server, switch the default certificates for the other Copy Services Manager server. Copy the dedicated server keystore file and common truststore file to the other Copy Services Manager server and update all property files as described in steps 8-18.
    If you do not switch the certificates for the other Copy Services Manager server, the Copy Services Manager Management server relationship is not established and fails with a connection error.
17. To use LDAP configuration for Copy Services Manager user authentication on the Copy Services Manager server, follow the next steps to switch the keystore of the csmAuth server as well.
18. Copy your new keystore file that you created in step 3 into the original csmAuth keystore directory.
    • path_prefix/opt/IBM/CSM/wlp/usr/servers/csmAuth/resources/security/ for z/OS
    • install dir/liberty/wlp/usr/servers/csmAuth/resources/security/ for distributed systems

    If you use dedicated keystore files for each Copy Services Manager server, such as myCsmKeyStore<ServerName>.jks, copy the corresponding keystore to the appropriate Copy Services Manager server.

19. Edit the bootstrap.properties file of the csmAuth server to point the server to use the new keystore file that contains your certificate that is used for the SSL connection. The file is at these locations.
    • path_prefix/opt/IBM/CSM/wlp/usr/servers/csmAuth/ for z/OS
    • install dir/liberty/wlp/usr/servers/csmAuth/ for distributed systems

    The default path name of the keystore_location is where you copied the keystore file, therefore you need to specify only your keystore file. Following example shows how to specify the copied keystore file located in csmAuth/resources/security.

    #relative to csmAuth/resources/security
    keystore_location=myCsmKeyStore<ServerName>.jks
    keystore_password=<assigned password>
    

    Note:

    • In the bootstrap.properties file, when you enter the value for keystore_location, use a slash ‘/’ as a path separator. When you use a backslash, you must add two backslashes together, such as ‘\\’. Adding a single backslash can cause the file to not be found. The Copy Services Manager server can even fail to start.
    • If you do not define a keystore_location, the server defaults to use a key.jks file in the resources/security directory, when the Copy Services Manager server is started.
    • If the specified keystore file is not found when, the Copy Services Manager server starts, a default file is created to serve browser connection requests to the Copy Services Manager GUI. This file has a certificate with an expiration of one year.
    • The password that is defined in keystore_password is eXclusive OR (XOR) encrypted with the securityUtility.
20. Restart the Copy Services Manager authentication server for the changes to take effect. You can check the csmAuth messages.log file to check whether the bootstrap.properties configuration changes were successful and the correct keystore and certificate is used. The csmAuth messages.log file is at these locations.
    • path_prefix/opt/IBM/CSM/wlp/usr/servers/csmAuth/logs for z/OS
    • install dir/liberty/wlp/usr/servers/csmAuth/logs for distributed systems