Keystore configuration

Network Deployment (Distributed operating systems), v8.0 > Secure applications and their environment > Secure communications > Secure communications using SSL

Keystore configuration

Overview

Key store types include...

hardware cryptographic
z/OS platform
IBM i platform
IBM Java Cryptography Extension (Default)
Java-based content management system

To retrieve custom keystores...

Add to java.security file

Specify provider list programmatically.

WAS retrieves keystore types via the object...

java.security.KeyStore

By default, the attribute...

java.security.Security.getAlgorithms("KeyStore")

...does not display a predefined list of keystore types.

IBMJCE security.xml

security.xml...
<keyStores xmi:id="KeyStore_1"
           name="NodeDefaultKeyStore"
           password="{xor}349dkckdd="
           provider="IBMJCE"
           location="${USER_INSTALL_ROOT}/config/cells/Cell01/nodes/Node01/key.p12"
           type="PKCS12"
           fileBased="true"
           hostList=""
           initializeAtStartup="true"
           readOnly="false"
           description="Default key store for Node01"
           usage="SSLKeys"
           managementScope="ManagementScope_1"/>
Attribute name Default Description
xmi:id Varies Used to reference this keystore from an SSL configuration. Make value unique within security.xml.
name CellDefaultKeyStore
CellDefaultTrustStore

password WebAS

description

usage SSLKeys
SSLKeys
KeySetKeys
RootKeys
DeletedKeys
DefaultSigners
RSATokenKeys
provider IBMJCE If left unspecified the first provider that implements the type specified is used.
location Default varies. Typically references a key.p12 file or a trust.p12 file in the node or cell directories of the configuration repository. These files are PKCS12 type keystores. Keystore location If the keystore is file-based, the location can reference any path in the file system of the node where the keystore is located. However, if the location is outside of the configuration repository, and you want to manage the keystore remotely from the admin console or from the wsadamin utility, then specify the hostList attribute that contains the host name of the node where it resides.
type PKCS11
JKS
JCEKS
PKCS12
PKCS11 (Java crypto device)
CMSKS
IBMi5OSKeyStore
JCERACFKS
JCECCAKS keystores (replacing JCE4758KS) - (z/OS crypto device)

fileBased Default: true Required for default keystores. Indicates a file-system keystore so you can use a FileInputStream or FileOutputStream for loading and storing the keystore.
hostList Remote hostname. There are no remotely managed keystores by default. All default keystores are managed locally in the configuration repository and synchronized out to each of the nodes. We can set the host name of a valid node for a keystore. When you use either the admin console or the wsadmin utility to manage certificates for this keystore, an MBean call is made to the node where the keystore exists for the approved operation. We can specify multiple hosts, although synchronization of the keystore operations are not guaranteed. For example, one of the hosts that is listed might be down when a specific operation is performed. Therefore, use multiple hosts in this list.
initializeAtStartup true Initialize the keystore during startup. Important for hardware cryptographic device acceleration.
readOnly false You cannot write to this keystore. That is, certain update operations on the keystore cannot be attempted and are not allowed. An example of a read-only keystore type is JCERACFKS on the z/OS platform. This type is read-only from the WebSphere certificate management standpoint, but you can also update it using the keystore management facility for RACF.
managementScope Default scope is the node scope for a base appservder environment and cell scope for an ND environment. References a particular management scope in which you can see this keystore. For example, if a hardware cryptographic device is physically located on a specific node, then create the keystore from a link to that node in the topology view under...

Security | Security Communications | SSL configurations

We can also use management scope to isolate a keystore reference. In some cases, you might need to allow only a specific application server to reference the keystore; the management scope is for that specific server.

CMS keystores

For CMSKS keystores, if supported by the provider, we can set attribute...

createStashFileForCMS=true

WAS will create a stash file named keystore.sth in the keystore location. For example, for a plug-in configuration...

${USER_INSTALL_ROOT}\profiles\AppSrv01/config/cells/Cell01/nodes/Node01/servers/webserver1/plugin-key.sth
<keyStores xmi:id="KeyStore_1132071489571"
           name="CMSKeyStore"
           password="{xor}HRYNFAtrbxEwOzpvbhw6MzM="
           provider="IBMCMSProvider"
           location="${USER_INSTALL_ROOT}\profiles\AppSrv01/config/cells/Cell01/nodes/Node01/servers/webserver1/plugin-key.kdb"
           type="CMSKS"
           fileBased="true"
           createStashFileForCMS="true"
           managementScope="ManagementScope_1132071489569"/> 
In this example the CMS provider is IBMi5OSJSSEProvider and the CMS type is IBMi5OSKeyStore...
<keyStores xmi:id="KeyStore_1132071489571"
           name="CMSKeyStore"
           password="{xor}HRYNFAtrbxEwOzpvbhw6MzM="
           provider="IBMi5OSJSSEProvider"
           location="${USER_INSTALL_ROOT}\profiles\AppSrv01/config/cells/Cell01/nodes/Node01/servers/webserver1/plugin-key.kdb"
           type="IBMi5OSKeyStore"
           fileBased="true"
           createStashFileForCMS="true"
           managementScope="ManagementScope_1132071489569"/> 
Hardware cryptographic keystores

For hardware cryptographic devices we can add custom property...

com.ibm.ssl.keyStoreSlot

...or configuration attribute...

slot="0"

The custom property is read before the attribute for backwards compatibility.

Related
Secure communications using SSL

+
Search Tips | Advanced Search

Attribute name	Default	Description
xmi:id	Varies	Used to reference this keystore from an SSL configuration. Make value unique within security.xml.
name	CellDefaultKeyStore CellDefaultTrustStore
password	WebAS
description
usage	SSLKeys	SSLKeys KeySetKeys RootKeys DeletedKeys DefaultSigners RSATokenKeys
provider	IBMJCE	If left unspecified the first provider that implements the type specified is used.
location	Default varies. Typically references a key.p12 file or a trust.p12 file in the node or cell directories of the configuration repository. These files are PKCS12 type keystores.	Keystore location If the keystore is file-based, the location can reference any path in the file system of the node where the keystore is located. However, if the location is outside of the configuration repository, and you want to manage the keystore remotely from the admin console or from the wsadamin utility, then specify the hostList attribute that contains the host name of the node where it resides.
type	PKCS11	JKS JCEKS PKCS12 PKCS11 (Java crypto device) CMSKS IBMi5OSKeyStore JCERACFKS JCECCAKS keystores (replacing JCE4758KS) - (z/OS crypto device)
fileBased	Default: true	Required for default keystores. Indicates a file-system keystore so you can use a FileInputStream or FileOutputStream for loading and storing the keystore.
hostList	Remote hostname. There are no remotely managed keystores by default. All default keystores are managed locally in the configuration repository and synchronized out to each of the nodes.	We can set the host name of a valid node for a keystore. When you use either the admin console or the wsadmin utility to manage certificates for this keystore, an MBean call is made to the node where the keystore exists for the approved operation. We can specify multiple hosts, although synchronization of the keystore operations are not guaranteed. For example, one of the hosts that is listed might be down when a specific operation is performed. Therefore, use multiple hosts in this list.
initializeAtStartup	true	Initialize the keystore during startup. Important for hardware cryptographic device acceleration.
readOnly	false	You cannot write to this keystore. That is, certain update operations on the keystore cannot be attempted and are not allowed. An example of a read-only keystore type is JCERACFKS on the z/OS platform. This type is read-only from the WebSphere certificate management standpoint, but you can also update it using the keystore management facility for RACF.
managementScope	Default scope is the node scope for a base appservder environment and cell scope for an ND environment.	References a particular management scope in which you can see this keystore. For example, if a hardware cryptographic device is physically located on a specific node, then create the keystore from a link to that node in the topology view under... Security \| Security Communications \| SSL configurations We can also use management scope to isolate a keystore reference. In some cases, you might need to allow only a specific application server to reference the keystore; the management scope is for that specific server.