Keystore configurations

Keystore configurations

+
Search Tips | Advanced Search

Use keystore configurations to define how the runtime for WAS loads and manages keystore types for SSL configurations.
By default, the attribute...
java.security.Security.getAlgorithms("KeyStore")

...does not display a predefined list of keystore types in the console. Instead, WAS retrieves all of the KeyStore types that can be referenced by the object...
java.security.KeyStore

...including keystores such as...

hardware cryptographic
z/OS platform
i5/OS platform
IBM Java Cryptography Extension (IBMJCE)
Java-based Content Management System

If you specify a keystore provider in the file...
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 is shown in the following sample code:
<keyStores xmi:id="KeyStore_1" 
           name="NodeDefaultKeyStore" 
           password="{xor}349dkckdd=" 
           provider="IBMJCE"
           location="${USER_INSTALL_ROOT}/config/cells/Node01Cell/nodes/Node01/key.p12" 
           type="PKCS12" 
           fileBased="true" 
           hostList="" 
           initializeAtStartup="true" 
           readOnly="false" 
           managementScope="ManagementScope_1"/>
For more information about default keystore configurations, see Default self-signed certificate configuration. Table 1 describes the attributes that are used in the sample code.

Table 1. keystore configurations

Attribute name Default Description

xmi:id Varies A value that issued 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 For JSSE keystore: CellDefaultKeyStore. For JSSE truststore: CellDefaultTrustStore. A name that is used to identify the keystore by sight. The name can determine if the keystore is a default keystore based upon whether the name ends with DefaultKeyStore or DefaultTrustStore.
password The default keystore password is WebAS. IBM recommends that this be changed as soon as possible. See Updating default key store passwords using scripting for more information. The password that is used to access the keystore name is also the default that is used to store keys within the keystore.
provider The default provider is IBMJCE. The Java provider that implements the type attribute (for example, PKCS12 type). The provider can be left unspecified and the first provider that implements the keystore type specified is used.
location The default varies, but 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. 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 you want to manage the keystore remotely from the console or from the wsadamin utility, then specify the hostList attribute that contains the host name of the node where it resides.
type The default Java crypto device keystore type is 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 The default is true. This option is required for default keystores. It indicates a file-system keystore so you can use a FileInputStream or FileOutputStream for loading and storing the keystore.
hostList The hostList attribute is used to specify a remote hostname so that the keystore can be remotely managed. 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. You can set the host name of a valid node for a keystore. When you use either the 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. You 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 The default is true. This option informs the runtime to initialize the keystore during startup. This option can be important for hardware cryptographic device acceleration.
readOnly The default is false. This option informs the configuration that 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 The default scope is the node scope for a base Application Server environment and the cell scope for a ND environment. This option 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. You can also use management scope to isolate a keystore reference. In some cases, you might need to allow only a specific appserver to reference the keystore; the management scope is for that specific server.

CMS keystores

You can set some provider-specific attributes in Content Management System (CMS) keystores.
If the CMSKS provider supports the attribute...
createStashFileForCMS

...and you set the attribute to true for CMSKS keystores, WAS creates a keystore.sth file in the keystore location that is referenced by the attribute.
For example, if the CMSKS keystore is available for a plug-in configuration and you set createStashFileForCMS to true...
<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"/>
...the stash file is created at...
 ${USER_INSTALL_ROOT}\profiles\AppSrv01/config/cells/Cell01/nodes/Node01/servers/webserver1/plugin-key.sth 
When you create 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/Cell01/nodes/Node01/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
Configure a hardware cryptographic keystore

You 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.
In certain environments, you can use the hardware cryptographic card for hardware acceleration. Either set the useForAcceleration attribute to true or set the custom property...
com.ibm.ssl.keyStoreUseForAcceleration

When you set the attribute to true, you are not required to configure a password. However, you cannot use the device to store keys.

Related concepts
Secure communications using Secure Sockets Layer

Attribute name	Default	Description
xmi:id	Varies	A value that issued 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	For JSSE keystore: CellDefaultKeyStore. For JSSE truststore: CellDefaultTrustStore.	A name that is used to identify the keystore by sight. The name can determine if the keystore is a default keystore based upon whether the name ends with DefaultKeyStore or DefaultTrustStore.
password	The default keystore password is WebAS. IBM recommends that this be changed as soon as possible. See Updating default key store passwords using scripting for more information.	The password that is used to access the keystore name is also the default that is used to store keys within the keystore.
provider	The default provider is IBMJCE.	The Java provider that implements the type attribute (for example, PKCS12 type). The provider can be left unspecified and the first provider that implements the keystore type specified is used.
location	The default varies, but 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.	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 you want to manage the keystore remotely from the console or from the wsadamin utility, then specify the hostList attribute that contains the host name of the node where it resides.
type	The default Java crypto device keystore type is 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	The default is true.	This option is required for default keystores. It indicates a file-system keystore so you can use a FileInputStream or FileOutputStream for loading and storing the keystore.
hostList	The hostList attribute is used to specify a remote hostname so that the keystore can be remotely managed. 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. You can set the host name of a valid node for a keystore. When you use either the 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. You 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	The default is true.	This option informs the runtime to initialize the keystore during startup. This option can be important for hardware cryptographic device acceleration.
readOnly	The default is false.	This option informs the configuration that 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	The default scope is the node scope for a base Application Server environment and the cell scope for a ND environment.	This option 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. You can also use management scope to isolate a keystore reference. In some cases, you might need to allow only a specific appserver to reference the keystore; the management scope is for that specific server.