Collective-wide SSH key configuration

The Liberty collectiveController-1.0 feature enables the default use of a single collective-wide SSH key pair for authentication between controllers and members/hosts. This collective-wide key pair is generated by default, or the collective host authentication configuration element can be configured to use an existing key pair.

When you create a new collective controller, you can specify, from the command line, a set of pre-existing keys to be used by the collective framework for SSH activity. See the following examples for sets of pre-existing keys.

File-based keys:

collective create controller --keystorePassword=key_store_password --sshPrivateKey=path_to_private_key --sshPrivateKeyPassword=private_key_password --sshPublicKey=path_to_public_key

Non-file-based keys on z/OS:

collective create controller --keystorePassword=key_store_password --safKeyring=safkeyring://keyring_name --safCertificateLabel=saf_certificate_label

collective create controller --keystorePassword=key_store_password --safKeyring=safkeyringhw://keyring_name --safCertificateLabel=saf_certificate_label --safKeystoreType=JCECCARACFKS --safKeystoreProvider=IBMJCECCA

collective create controller --keystorePassword=key_store_password --safKeyring=safkeyringhybrid://keyring_name --safCertificateLabel=saf_certificate_label --safKeystoreType=JCEHYBRIDRACFKS --safKeystoreProvider=IBMJCEHYBRID

The previous commands generate the following configuration elements, which override collective host information:

File-based keys:

<collectiveHostAuthInfo 
     sshPrivateKeyPath="path_to_private_key"
     sshPublicKeyPath="path_to_public_key"
     sshPrivateKeyPassword="private_key_password"/>

Non-file-based keys on z/OS:

<collectiveHostAuthInfo
     safKeyring="safkeyring://keyring_name"
     safCertificateLabel="saf_certificate_label"/>

<collectiveHostAuthInfo
     safKeyring="safkeyringhw://keyring_name"
     safCertificateLabel="saf_certificate_label"
     safKeystoreType="JCECCARACFKS"
     safKeystoreProvider="IBMJCECCA"/>

<collectiveHostAuthInfo
     safKeyring="safkeyringhybrid://keyring_name"
     safCertificateLabel="saf_certificate_label"
     safKeystoreType="JCEHYBRIDRACFKS"
     safKeystoreProvider="IBMJCEHYBRID"/>

When you use non-file-based keys on z/OS, the safKeystoreType and safKeystoreProvider entries are optional. You can specify the safKeystoreType attribute and omit the safKeystoreProvider attribute. If the safKeystoreProvider attribute is omitted, the system picks the appropriate provider based on the provider order of preference that is established through Java™ API calls or through the java.security file.

The following options are supported for the safKeystoreType attribute, the safKeystoreProvider attribute, and the safKeyring URL prefixes in respective order:

safKeystoreType: JCERACFKS, JCECCARACFKS, and JCEHYBRIDRACFKS.
safKeystoreProvider: IBMJCE, IBMJCECCA, and IBMJCEHYBRID.
safKeyring URL prefixes: safkeyring://, safkeyringhw://, and safkeyringhybrid://.
Prefixes of safkeyring:///, safkeyringhw:///, and safkeyringhybrid:/// are also allowed.

For more information about the IBMJCECCA provider, see IBM z Platform Java Security Frequently Asked Questions. For more information about the IBMJCEHYBRID provider, see IBM JCE Hybrid Provider Reference Guide.

Configuration Attributes

sshPrivateKeyPath: This attribute specifies the path and file name of the existing user specified private key file. If set, the sshPublicKeyPath attribute must also be configured. If not set, the controller will either use SAF authentication if configured, or generate an SSH key pair at the default location ${server.output.dir}/resources/security/ssh.
sshPublicKeyPath: This attribute specifies the path and file name of the existing user specified public key file. If set, the sshPrivateKeyPath attribute must also be configured. If not set, the controller will either use SAF authentication if configured, or generate an SSH key pair at the default location ${server.output.dir}/resources/security/ssh.
sshPrivateKeyPassword: This attribute specifies the password for the private key. This attribute has no default value.
safKeyring: This attribute specifies an existing SAF key ring to use for the collective-wide SSH key pair. The specified URL location of the key ring must be in the format that is required for the keystore type. Use safkeyring://keyring_name or safkeyring:///keyring_name for the JCERACFKS keystore type. Use safkeyringhw://keyring_name or safkeyringhw:///keyring_name for the JCECCARACFKS keystore type. Use safkeyringhybrid://keyring_name or safkeyringhybrid:///keyring_name for the JCEHYBRIDRACFKS keystore type.
If set, the safCertificateLabel attribute must also be configured. If not set, the controller will either use a configured SSH key pair, or generate an SSH key pair at the default location ${server.output.dir}/resources/security/ssh.
safCertificateLabel: This attribute specifies an existing SAF Certificate Label. If set, the safKeyring attribute must also be configured. If not set, the controller will either use a configured SSH key pair, or generate an SSH key pair at the default location ${server.output.dir}/resources/security/ssh.
safKeystoreType: This attribute specifies the type of keystore that is used when processing the key ring under the safKeyring attribute. Valid keystore types are JCERACFKS, JCECCARACFKS, and JCEHYBRIDRACFKS. This attribute is optional. If a keystore type is not specified, the JCERACFKS keystore type is used.
safKeystoreProvider: This attribute specifies the keystore provider that is used when processing the keystore that is associated with the key ring under the safKeyring attribute. The allowed providers are IBMJCE, IBMJCECCA, and IBMJCEHYBRID. This attribute is optional. By default, no provider is used. The system picks the most appropriate provider based on provider setup.