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.
collective create controller --keystorePassword=key_store_password --sshPrivateKey=path_to_private_key --sshPrivateKeyPassword=private_key_password --sshPublicKey=path_to_public_key
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:
<collectiveHostAuthInfo
sshPrivateKeyPath="path_to_private_key"
sshPublicKeyPath="path_to_public_key"
sshPrivateKeyPassword="private_key_password"/>
<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.
- safKeystoreType:
JCERACFKS
,JCECCARACFKS
, andJCEHYBRIDRACFKS
. - safKeystoreProvider:
IBMJCE
,IBMJCECCA
, andIBMJCEHYBRID
. - safKeyring URL prefixes:
safkeyring://
,safkeyringhw://
, andsafkeyringhybrid://
.Prefixes of
safkeyring:///
,safkeyringhw:///
, andsafkeyringhybrid:///
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
orsafkeyring:///keyring_name
for theJCERACFKS
keystore type. Usesafkeyringhw://keyring_name
orsafkeyringhw:///keyring_name
for theJCECCARACFKS
keystore type. Usesafkeyringhybrid://keyring_name
orsafkeyringhybrid:///keyring_name
for theJCEHYBRIDRACFKS
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
, andJCEHYBRIDRACFKS
. This attribute is optional. If a keystore type is not specified, theJCERACFKS
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
, andIBMJCEHYBRID
. This attribute is optional. By default, no provider is used. The system picks the most appropriate provider based on provider setup.