Keystore configurations for SSL

WAS v8.5 > Secure applications > Secure communications > Secure communications using SSL
Keystore configurations for SSL

Keystore configurations define how the runtime loads keystore types for SSL configurations.
By default, the java.security.Security.getAlgorithms("KeyStore") attribute does not display a predefined list of keystore types in the dmgr console. Instead, WAS retrieves all of the KeyStore types that can be referenced by the java.security.KeyStore object, including...

hardware cryptographic
z/OS platform
IBM i platform
IBM Java Cryptography Extension (IBMJCE)
Java-based content management system (CMS)-provider keystores

If we specify a keystore provider in the java.security file or add it to the provider list programmatically, WebSphere Application Sever also retrieves custom keystores. The retrieval list depends upon the java.security configuration for that platform and process.

IBMJCE file-based keystores (JCEKS, JKS, and PKCS12)

A typical IBMJCE file-based keystore configuration...
<keyStores xmi:id="KeyStore_1" 
           name="NodeDefaultKeyStore" 
           password="{xor}349dkckdd=" provider="IBMJCE"
           location="${USER_INSTALL_ROOT}/config/cells/cellname/nodes/nodename/key.p12" 
           type="PKCS12" 
           fileBased="true" 
           hostList="" initializeAtStartup="true" readOnly="false" 
           description="Default key store for nodename" 
           usage="SSLKeys" 
           managementScope="ManagementScope_1"/>
Attributes...

Attribute name Default Description
xmi:id Varies Used to reference the keystore from another area in the configuration, for example, from an SSL configuration. Make this value unique within the security.xml file.
name NodeDefaultKeyStore
NodeDefaultTrustStore The name can determine if the keystore is a default keystore based upon whether the name ends with DefaultKeyStore or DefaultTrustStore.
password WebAS Access the keystore name is also the default used to store keys within the keystore.
description No default A description of the keystore.
usage
Values include: SSLKeys, KeySetKeys, RootKeys, DeletedKeys, DefaultSigners, RSATokenKeys.
provider IBMJCE. The Java provider that implements the type attribute (for example, PKCS12 type). The provider can be unspecified and the first provider that implements the keystore type specified is used.
location Typically key.p12 or trust.p12 file in the node or cell directories of the configuration repository. These files are PKCS12 type keystores. The keystore location reference. 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 to manage the keystore remotely from the dmgr console or from the wsadamin utility, then specify the hostList attribute containing the host name of the node where it resides.
type PKCS12 This type specifies the keystore. Valid types can be those returned by the java.security.Security.getAlgorithms("KeyStore") attribute. These types include the following keystore types, and availability depends on the process and platform java.security configuration:

JKS
JCEKS
PKCS12
PKCS11 (Java crypto device)
CMSKS
IBMi5OSKeyStore
JCERACFKS
JCECCAKS keystores (replacing JCE4758KS) - (z/OS crypto device)

fileBased true File-system keystore used with FileInputStream or FileOutputStream for loading and storing the keystore. Required.
hostList 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. The option manages a keystore remotely. We can set the host name of a valid node for a keystore. When we use either the dmgr 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 Informs the runtime to initialize the keystore during startup. This option can be important for hardware cryptographic device acceleration.
readOnly false Informs the configuration that we cannot write to this keystore. 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 we can also update it using the keystore management facility for RACF .
managementScope Node scope for a WAS Base environment and the cell scope for a WAS ND environment. Particular management scope in which we 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, we might need to allow only a specific application server to reference the keystore; the management scope is for that specific server.

CMS keystores

We can set some provider-specific attributes in CMS keystores.
If the CMSKS provider supports the createStashFileForCMS attribute, and you set the attribute to true for CMSKS keystores, WAS creates an .sth file in the keystore location referenced by the attribute. The .sth extension is appended to the keystore name. For example, if the CMSKS keystore is available for a plug-in configuration and you set createStashFileForCMS to true, the stash file that is represented in the following sample code is created in the ${USER_INSTALL_ROOT}\profiles\AppSrv01/config/cells/myhostCell01/nodes/nodename/servers/webserver1/plugin-key.sth path.
<keyStores xmi:id="KeyStore_1132071489571" 
           name="CMSKeyStore" 
           password="{xor}HRYNFAtrbxEwOzpvbhw6MzM=" provider="IBMCMSProvider" 
           location="${USER_INSTALL_ROOT}\profiles\AppSrv01/config/cells/myhostCell01/nodes/nodename/servers/webserver1/plugin-key.kdb" 
           type="CMSKS"
           fileBased="true" createStashFileForCMS="true"
           managementScope="ManagementScope_1132071489569"/>
When creating a CMS keystore, the CMS provider is IBMi5OSJSSEProvider, and the CMS type is IBMi5OSKeyStore, as shown in the following sample code:
<keyStores xmi:id="KeyStore_1132071489571" 
           name="CMSKeyStore" 
           password="{xor}HRYNFAtrbxEwOzpvbhw6MzM=" 
           provider="IBMi5OSJSSEProvider" 
           location="${USER_INSTALL_ROOT}\profiles\AppSrv01/config/cells/myhostCell01/nodes/nodename/servers/webserver1/plugin-key.kdb" 
           type="IBMi5OSKeyStore"
           fileBased="true" 
           createStashFileForCMS="true" 
           managementScope="ManagementScope_1132071489569"/>
Hardware cryptographic keystores

For cryptographic device configuration, see Key management for cryptographic uses .
We can add a slot either as the custom property, com.ibm.ssl.keyStoreSlot, or as the configuration attribute, slot="0". The custom property is read before the attribute for backwards compatibility.

Related concepts:

Secure communications using SSL

+
Search Tips | Advanced Search

Attribute name	Default	Description
xmi:id	Varies	Used to reference the keystore from another area in the configuration, for example, from an SSL configuration. Make this value unique within the security.xml file.
name	NodeDefaultKeyStore NodeDefaultTrustStore	The name can determine if the keystore is a default keystore based upon whether the name ends with DefaultKeyStore or DefaultTrustStore.
password	WebAS	Access the keystore name is also the default used to store keys within the keystore.
description	No default	A description of the keystore.
usage		Values include: SSLKeys, KeySetKeys, RootKeys, DeletedKeys, DefaultSigners, RSATokenKeys.
provider	IBMJCE.	The Java provider that implements the type attribute (for example, PKCS12 type). The provider can be unspecified and the first provider that implements the keystore type specified is used.
location	Typically key.p12 or trust.p12 file in the node or cell directories of the configuration repository. These files are PKCS12 type keystores.	The keystore location reference. 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 to manage the keystore remotely from the dmgr console or from the wsadamin utility, then specify the hostList attribute containing the host name of the node where it resides.
type	PKCS12	This type specifies the keystore. Valid types can be those returned by the java.security.Security.getAlgorithms("KeyStore") attribute. These types include the following keystore types, and availability depends on the process and platform java.security configuration: JKS JCEKS PKCS12 PKCS11 (Java crypto device) CMSKS IBMi5OSKeyStore JCERACFKS JCECCAKS keystores (replacing JCE4758KS) - (z/OS crypto device)
fileBased	true	File-system keystore used with FileInputStream or FileOutputStream for loading and storing the keystore. Required.
hostList	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.	The option manages a keystore remotely. We can set the host name of a valid node for a keystore. When we use either the dmgr 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	Informs the runtime to initialize the keystore during startup. This option can be important for hardware cryptographic device acceleration.
readOnly	false	Informs the configuration that we cannot write to this keystore. 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 we can also update it using the keystore management facility for RACF .
managementScope	Node scope for a WAS Base environment and the cell scope for a WAS ND environment.	Particular management scope in which we 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, we might need to allow only a specific application server to reference the keystore; the management scope is for that specific server.