Configuring certificates for managed z/VM systems

When you configure Wave to connect securely to z/VM systems and validate the connections' server certificate, the certificate validation process will fail unless the client side of the connection (the Wave server, and your workstation when using 3270/CLC) trusts the z/VM server certificate's certificate chain.

If the z/VM system's server certificate is signed by a certificate authority (CA) that all clients (including the Wave server and your workstation, as appropriate) in your enterprise trust, no additional configuration is required. In this case, any required certificates have already been installed into the Wave server's Java virtual machine (JVM) and your client workstation by their respective administrators.

In other cases, you must perform manual configuration steps:

You must add any necessary certificates to the Wave server's JVM, as described in Adding trusted server certificates to the Wave server.
If you intend to use Wave's 3270 or CLC connection capabilities, you must add any necessary certificates on each workstation running the Wave client application, as described in Adding trusted server certificates to a Windows workstation.

When the z/VM network security administrators export each z/VM system's server certificate, they must choose asn.1, base64 format in gskkyman, and transfer them to their destinations in binary mode.

The number of necessary certificates you need to import will vary based on the size of the certificate chains your z/VM security administrators use, and which certificate authorities already have entries in your enterprise JVM's trusted certificate keystores and in your Windows workstations.

Adding trusted server certificates to the Wave server

Using the keytool utility that is supplied with all Java Runtime Environments (JREs), you can import Secure Socket Layer (SSL) and Transport Layer Security (TLS) certificates into the Wave server's Java keystore of trusted certificates. This keystore should already exist. Often, the following Linux shell command will show its location:

ls -L $JAVA_HOME/lib/security/cacerts

Or, ask your Linux administrator for the keystore's location and password.

The JVM's default keystore password is changeit, but your installation should have changed the password after installation. IBM Wave uses this keystore if the /usr/wave/install/waveLdap.jks keystore contains no trusted certificate entries.

Each of the following keytool commands will prompt for the keystore's password, so you must know that in order to proceed.

Open a command-line prompt and navigate to the jre_home_path/bin directory.

Enter the following command:

keytool -import -storepass storepass_password -noprompt \ 
-alias unique_certificate_alias_for_keystore \  
-keystore jre_home_path/lib/security/cacerts -trustcacerts -file path_to_certificate_file

Note: The keytool utility requires aliases to be unique within a keystore. IBM Wave does not use the alias values, so it imposes no requirements on them.

To list the installed certificates, enter one of the following commands:

keytool -keystore jre_home_path/lib/security/cacerts -storepass changeit -list

This version of the command includes more detailed output:

keytool -keystore jre_home_path/lib/security/cacerts -list \
-v | awk '/Alias name:/{print "---";flag=1}/Extensions:/{flag=0}flag'

Adding trusted server certificates to a Windows workstation

Use your enterprise's established procedure for adding trusted server certificates to workstations that will run the Wave client application and access managed guests using its 3270 or CLC features.

Notes:

Many enterprises use policies to prevent you from adding certificates to the JVM running Wave's client application, but if your policy allows adding certificates to the JVM yourself, you can:
- Open a command prompt with Administrator privileges.
- Change to the jre_home_path/bin directory.
- Run the commands shown in Adding trusted server certificates to the Wave server.
Many enterprises that prevent you from adding certificates to the JVM from the command line delegate the certificate store function to Windows. In this case, you can often use Microsoft's Management Console to add the certificates.
- On Windows 10, typically you should select the local machine store's trusted root certification authorities store, but consult your enterprise's procedures.