Generating collective controller SSL keys

You can use the collective utility genKey command to generate a keystore in Java™ keystore (JKS) format. The keystore contains a personal certificate that enables Secure Sockets Layer (SSL) communication with the collective controller.

Before you begin

Create a collective controller. See Configuring a Liberty collective.

About this task

Remote JMX connections to a collective controller use SSL and require suitable SSL keys. The collective utility genKey command generates a keystore that contains a personal certificate which the collective controller trusts. The generated keystore also includes a public signer certificate so it can function as a trust store.

For a Java virtual machine (JVM), such as a collective member server or a non-Liberty server, to connect to a collective controller, the JVM must have a keystore that contains a key which the collective controller trusts. The genKey command generates this keystore. After the JVM has the keystore, the JVM can connect to the collective controller and the collective controller can return its key. This return of the collective controller key to the JVM is called the SSL handshake.

For the JVM to add the collective controller key to the JVM truststore, the --autoAcceptCertificates option must be used. If the --autoAcceptCertificates option is not used, the user is prompted to add the key to the truststore.

Procedure

Run the collective genKey command to generate a JKS keystore.

wlp/bin/collective genKey [--host=collectiveControllerHost --password=collectiveControllerAdminUserPassword --port=collectiveControllerHTTPSPort --user=collectiveControllerAdminUserID --keystorePassword=generatedKeystorePassword --autoAcceptCertificates]

To reduce the number of options needed, use the --controller option instead of --user, --password, --host, and --port.

wlp/bin/collective genKey [--controller=collectiveControllerAdminUserID:collectiveControllerAdminUserPassword@collectiveControllerHost:collectiveControllerHTTPSPort --keystorePassword=generatedKeystorePassword --autoAcceptCertificates]

For example, for a collective controller on host machineA that uses port 1090 and has a collective controller administrative user Admin1 with password Admin1pwd, run the following command to generate a keystore and set its password to kspwd:

collective genKey --host=machineA --password=Admin1pwd --port=1090 --user=Admin1 --keystorePassword=kspwd --autoAcceptCertificates

To reduce the number of options needed, use the --controller option instead of --user, --password, --host, and --port.

collective genKey --controller=Admin1:Admin1pwd@machineA:1090  --keystorePassword=kspwd --autoAcceptCertificates

This example includes the required settings for the genKey command:

--host=collectiveControllerHost: The host name of the target collective controller
--password=collectiveControllerAdminUserPassword: The password of the administrative user for the target collective controller. If no password is defined, you are prompted for the password of the administrative user specified by the --user setting.
--port=collectiveControllerHTTPSPort: The HTTPS port number of the target collective controller
--user=collectiveControllerAdminUserID: An administrative user of the target collective controller
--keystorePassword=generatedKeystorePassword: The password for the generated keystore. If you specify a password and no value is defined, you are prompted for a password.

The genKey command also has optional settings:

--autoAcceptCertificates

Automatically trust SSL certificates during this command.

--certificateSubject=DN

The distinguished name (DN) of the generated SSL certificate. The default DN is:

CN=localhost,OU=client,O=ibm,C=usCN=localhost,OU=client,O=ibm,C=usCN=localhost,OU=client,O=ibm,C=usCN=localhost,OU=client,O=ibm,C=us

--certificateValidity=numberOfDays

The number of days the generated SSL certificate is valid. The default validity period is 1825 days, or 5 years. The minimum validity period is 365 days.

--keystoreFile=filePath

The file to which the keystore is written. The default is the key.jks file in the current directory.

--key=key

A key to use for aes encoding. The product hashes the specified key string to produce an encryption key to use to encrypt and decrypt the password. To provide the key to the server, define a variable wlp.password.encryption.key whose value is the key. If you do not specify this option, the product supplies a default key.