Keystore configurations for SSL

Keystore configurations for SSL

Use keystore configurations to define how the runtime for WebSphere Application Server loads and manages 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 administrative 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 Certificate Management Services (CMS)

If we specify a keystore provider in the java.security file or add it to the provider list programmatically, WebSphere Application Server 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/myhostNode01Cell/nodes/myhostNode01/key.p12" 
   type="PKCS12" 
   fileBased="true" 
   hostList="" 
   initializeAtStartup="true" 
   readOnly="false" 
   description="Default key store for myhostNode01" 
   usage="SSLKeys" 
   managementScope="ManagementScope_1"/>
For more information about default keystore configurations, see Default chained certificate configuration in SSL.
Attributes used in the sample code...

Attribute name Default Description
xmi:id Varies 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 JSSE keystore: CellDefaultKeyStore
JSSE truststore: CellDefaultTrustStore A name 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. Change as soon as possible. The password used to access the keystore name is also the default used to store keys within the keystore.
description No default A description of the keystore.
usage An attribute specifying what the keystore is used for. Valid values are: SSLKeys, KeySetKeys, RootKeys, DeletedKeys, DefaultSigners, RSATokenKeys.
provider The default provider is 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 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 we want to manage the keystore remotely from the administrative console or from the wsadamin utility, then specify the hostList attribute containing 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 we can use a FileInputStream or FileOutputStream for loading and storing the keystore.
hostList 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. We can set the host name of a valid node for a keystore. When we use either the administrative 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 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. 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 .
(ZOS) Optionally, we can configure writable keyring support that enables additional keystore configurations for use by the certificate management function. See Create writable SAF keyrings and Use writable SAF keyrings for more information on configuring and using writable key store configuration objects.

managementScope The default scope is the node scope for a base Application Server environment and the cell scope for a Network Deployment environment. This option references a 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.

(ZOS) z/OS keystores

WAS supports IBMJCE file-based keystores, Java Cryptography Extension Key Stores (JCEKS), Java Key Stores (JKS), and Public Key Cryptography Standards 12 (PKCS12), and z/OS-specific keystores. The IBMJCE file-based keystore support on z/OS is fully compatible with and similar to the support on the distributed platform.

The IBMJCECCA provider extends and replaces the IBMJCE4758 provider from earlier releases. The IBMJCECCA provider and the IBMJCE4758 provider are functionally equivalent. The IBMJCECCA provider supports four keystores: JCECCAKS (JCE4758KS) and JCECCARACFKS (JCE4758RACFKS).

The JCECCAKS keystore uses keys stored in the z/OS hardware and managed by ICSF. The JCECCARACFKS keystore handles certificates managed and stored in RACF keyrings, and the keys are stored in the z/OS hardware. The JCE4758KS and JCE4758RACFKS keystores are included for downward compatibility and are deprecated. The JCECCAKS keystore extends and replaces the JCE4758KS keystore. The JCECCARACFKS keystore extends and replaces the JCE4758RACFKS keystore.

The z/OS platform offers three additional keystores types that can be used for WAS on z/OS:

JCECCAKS keystores (replacing JCE4758KS) use keys stored in the z/OS hardware and keys that are managed in Integrated Cryptographic Services Facility (ICSF).
JCERACFKS keystores are a Resource Access Control Facility (RACF) - based keystores used to support keys and certificates that are contained in a RACF keystore. Key material stored in ICSF is not supported with this keystore type.
JCECCARACFKS (extending and replacing JCE4758RACFKS) keystores are RACF - based keystores used to support certificates contained in a RACF keystore along with keys stored in z/OS hardware. The ICSF option with RACF RACDCERT must be specified.

The keystore type, JCERACFKS for the IBMJCE provider and JCECCARACFKS for the IBMJCECCA provider, are only available on the z/OS platform where SAF is available.
Use the administrative console to extract a personal certificate into HFS as a Base64-encoded ASCII data type or as a Binary DER data type. However, if the keystore type of the SSL configuration is JCERACFKS , a 0 bytes file is created in HFS.
To be compatible with the JCE keystore in requiring a password, the JCERACFKS require a password but that password must be password. Security for this keystore is not really protected using a password as other keystore types, but rather it is based on the identity of the executing thread for protection with RACF. This password is for the keystore file specified in the Path field.

An IBMJCE provider can only support the JCERACFKS keystore in the set of z/OS-specific keystores listed previously. The IBMJCE provider cannot use the JCECCAKS or JCECCARACFKS keystore material since it is specific to the hardware.

An IBMJCECCA provider can support software key materials for the JCERACFKS, JKS, and JCEKS keystores, and take advantage of the hardware acceleration.

A new keystore class, JceRACFKeyStore, has been added to the IBMJCE and IBMJCECCA providers. Use this class when you retrieve certificates and keys from a keyring because this keystore allows WAS to read from a keyring. However, if the server attempts to write data to the keyring, an IOException is thrown. While the RACFInputStream works with any keystore, it is possible that data stored in RACF could be inadvertently written to an Hierarchical File System (HFS) file if the server uses a keystore other than the JceRACFKeyStore class.

RACFInputStream can access keys and certificates stored in a System Authorization Facility (SAF) keyring implementation using either of the following methods:

Use RACFInputStream directly to pass in a newly-created instance to the JceRACFKeyStore class
Use URLStreamHandler to call RACFInputStream, then pass the instance to the JceRACFKeyStore class
See RACF keyring setup.
All JAVA RACF services, including the JceRACFKeyStore and RACFInputStream, use the R_datalib (IRRSDL00) service to retrieve certificates from RACF. However, to use this service, we must obtain authorization for R_datalib before we use any JAVA RACF classes. For more information on how to set up the necessary authorizations, see OS/390 Security Server Callable Services guide.

CMS keystores

We can set some provider-specific attributes in CMS keystores.

(ZOS) (Dist) If the CMSKS provider supports the createStashFileForCMS attribute, and we 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 we set createStashFileForCMS to true, the stash file represented in the following sample code is created in...
${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"/>
When we 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"/>
(iSeries) Note: The IBM i keystore type IBMi5OSKeyStore does not recognize or generate .sth password stash files. Instead it keeps an internal record of the password for the .kdb keystore file where it is created. If the .kdb file is moved, the password is no longer associated with the keystore. In that case, the Digital Certificate Manager (DCM) must be used to recreate the internal record of the password for the .kdb key store file. See Recreating the .kdb keystore internal password record.
(iSeries) Attention: When we create chained personal certificates or use the requestCACertificate task with the IBMi5OSKeyStore, the IBMi5OSJSSEProvider requires that the signer for each part of the chain be present in the keystore prior to creation of the new certificate. Therefore, import the signer into the IBMi5OSKeyStore keystore before creating the new certificate.

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:

Secure communications using SSL
(iSeries) Recreating the .kdb keystore internal password record

Attribute name	Default	Description
xmi:id	Varies	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	JSSE keystore: CellDefaultKeyStore JSSE truststore: CellDefaultTrustStore	A name 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. Change as soon as possible.	The password used to access the keystore name is also the default used to store keys within the keystore.
description	No default	A description of the keystore.
usage	An attribute specifying what the keystore is used for.	Valid values are: SSLKeys, KeySetKeys, RootKeys, DeletedKeys, DefaultSigners, RSATokenKeys.
provider	The default provider is 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	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 we want to manage the keystore remotely from the administrative console or from the wsadamin utility, then specify the hostList attribute containing 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 we can use a FileInputStream or FileOutputStream for loading and storing the keystore.
hostList	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. We can set the host name of a valid node for a keystore. When we use either the administrative 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 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.	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 . (ZOS) Optionally, we can configure writable keyring support that enables additional keystore configurations for use by the certificate management function. See Create writable SAF keyrings and Use writable SAF keyrings for more information on configuring and using writable key store configuration objects.
managementScope	The default scope is the node scope for a base Application Server environment and the cell scope for a Network Deployment environment.	This option references a 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.