Keystores

Liberty can create only a keystore type of Java™ Keystore (JKS). Support for other types of keystore in Liberty can depend on what is supported by the underlying Java Runtime Environment (JRE).

You can encrypt (AES) or encode (XOR) passwords. Use the securityUtility command to set the password encoding type.

For more information on configuration attributes of the keystore element, see SSL configuration attributes.

PKCS12 keystore

Public Key Cryptography Standards #12 (PKCS12) keystore is an industry standard keystore type, which makes it compatible with other products.

PKCS12 is the Liberty default keystore type.

Through 19.0.0.2, PKCS12 keystore can be used, but not created by Liberty, when you use the IBM® JRE.

The following example is for the PKCS12 keystore configuration:

    <keyStore id="samplePKCS12KeyStore"
     location="MyKeyStoreFile.p12"
     type="PKCS12" password="myPassword" />

JKS and JCEKS

Java Keystore (JKS) and Java Cryptography Extensions Keystore (JCEKS) are common between the IBM JRE and the Oracle JRE, and can be configured the same using either JRE.

Public Key Cryptography Standards #12 (PKCS12) keystore is an industry standard keystore type, which makes it compatible with other products. PKCS12 is the Liberty default keystore type.

An example of JKS keystore configuration is as follows:

<keyStore id="samplePKCS12KeyStore"
      location="MyKeyStoreFile.jks"
      type="JKS" password="myPassword" />

Through 19.0.0.2, JKS is the default keystore type in Liberty, and the only type of keystore Liberty can create. If no keystore type is specified in the configuration, JKS is used.

An example of JKS keystore configuration is as follows:

     <keyStore id="sampleJKSKeyStore"
      location="MyKeyStoreFile.jks"
      type="JKS" password="myPassword" />

An example of JCEKS keystore configuration is as follows:

    <keyStore id="sampleJCEKSKeyStore"
     location="MyKeyStoreFile.jceks"
     type="JCEKS" password="myPassword" />

PKCS11 keystore

A hardware cryptographic keystore can be configured so that the Liberty server can be used to provide cryptographic token support.

The user must provide a hardware device-specific configuration file. The configuration file is a text file that contains entries in the format of attribute = value. The file must contain at least the name and library attribute. For example:


name = HWDevice
library = /opt/foo/lib/libpkcs11.so

The name attribute is a name that is being given to this instance of the device. The library attribute contains a path to the library provided by the hardware device to access the device. The configuration file can also contain configuration data specific to the hardware device.

To configure a PKCS11 keystore in Liberty the keystore element must contain the following fields:

id - Uniquely identify the keystore element in the configuration.
location - The path to the hardware device-specific configuration file.
type - PKCS11 must be specified as the keystore type.
fileBased - Must be false to identify this keystore as a device.
password - Password that is needed to access keys in the device.
provider - The provider that is needed. For the IBM JRE, the value must be IBMPKCS11Impl and for Oracle JRE it must be SunPKCS11.

Here is an example configuration:


<keyStore id="hwKeyStore" 
          location="${server.config.dir}/HWCrypto.cfg" 
          type="PKCS11" 
          fileBased="false" 
          password="{xor}Lz4sLCgwLTs=" 
          provider="IBMPKCS11Impl"/>

CMS keystore

CMS keystore can be configured, but not created by Liberty, when using the IBM JRE but some special configuration is required. The CMS provider is not available by default on the IBM JRE, therefore it must be added to the provider list in the java.security file of the IBM JRE. In the following example, the com.ibm.security.cmskeystore.CMSProvider class is added to the end of the list. Ensure that the provider number is correct in the provider list. Liberty does not use the CMS keystore stash file to gain access to the keystore.

    security.provider.1=com.ibm.jsse2.IBMJSSEProvider2
    security.provider.2=com.ibm.crypto.provider.IBMJCE
    security.provider.3=com.ibm.security.jgss.IBMJGSSProvider
    security.provider.4=com.ibm.security.cert.IBMCertPath
    security.provider.5=com.ibm.security.sasl.IBMSASL
    security.provider.6=com.ibm.xml.crypto.IBMXMLCryptoProvider
    security.provider.7=com.ibm.xml.enc.IBMXMLEncProvider
    security.provider.8=org.apache.harmony.security.provider.PolicyProvider
    security.provider.9=com.ibm.security.jgss.mech.spnego.IBMSPNEGO
    security.provider.10=com.ibm.security.cmskeystore.CMSProvider

To use the CMS keystore, the configuration in the server.xml file is as follows:

    <keyStore id="sampleCMSKeyStore" 
     password="myPassword"
     location="MyKeyStoreFile.kdb"
     provider="IBMCMSProvider"
     type="CMSKS"/>

RACF keyring types

RACF® keyrings can be used, but not created by Liberty, as keystores on z/OS®. The two keyring types available are JCERACFKS and JCEHYBRIDRACFKS.

JCERACFKS keystore

JCERACFKS is a RACF keyring type. You must set up RACF before Liberty can use it. Supply a URL to the keyring in the location attribute, and set the fileBased attribute to false.

An example of using the JCERACFKS keystore is as follows:

<keyStore id="sampleKeyring" location="safkeyring:///Keyring" 
 type="JCERACFKS" password="password" fileBased="false"
 readOnly="true" />

JCEHYBRIDRACFKS keystore

JCEHYBRIDRACFKS is a special keyring that checks whether a hardware keystore type is configured. If the JCEHYBRIDRACFKS keystore is not configured, the RACF keyring is used. It is supported on IBM Java 7 SR3 and later. You must edit the java.security file and add the com.ibm.crypto.ibmjcehybrid.provider.IBMJCEHYBRID class to the beginning of the provider list. Ensure that the provider numbers are adjusted for the new entry.

An example of using the JCEHYBRIDRACFKS keystore is as follows:

<keyStore id="sampleHybridKeyring" location="safkeyringhybrid:///HybridKeyring" 
 type="JCEHYBRIDRACFKS" password="{xor}Lz4sLCgwLTs=" fileBased="false" 
 readOnly="true" />