Start of changes for 11.0.15.0

IBMZSecurity

The IBMZSecurity provider provides keystore functions for JCERACFKS keystore. The provider contains an implementation of the java.security.KeyStore class (com.ibm.crypto.zsecurity.provider.JceRACFKeyStore) and a utility for managing public and private key pairs and associated certificates (zseckeytool).

Overview

A keystore is a Java™ object that contains a collection of keys and certificates that are referenced by unique labels or alias names. For most Java keystores, the persistent data is stored in a file. However, the persistent data for a JCERACFKS keystore is stored in the system Resource Access Control Facility (RACF®) database and connected to a RACF key ring. This type of keystore is available only on z/OS® systems that have RACF installed. Due to the nature of the RACF and key rings, the behavior of JCERACFKS keystore during update operations differs from the behavior of file-based keystore.

The zseckeytool uses JCERACFKS keystore instead of file-based keystore, for storing the keys and certificates. Keystore functions for file-based keystore types, such as JCEKS, are provided by the SUN and SunJCE providers. In earlier releases of the SDK, JCERACFKS keystore management was provided by the IBMJCE provider and the keytool utility.

The command-line options for managing key pairs and certificates by using the zseckeytool utility are similar to the keytool utility in OpenJDK. For general information about the keytool utility, see OpenJDK keytool documentation. The zseckeytool differs from the keytool in the following ways:
  • Always use the -keystore option for JCERACFKS keystore because it does not have a default value. Use the -keystore option to specify the RACF key ring by using one of the following formats:
    • Start of changes for 11.0.20.1A string that contains the RACF keystore-independent safkeyring URL. When you use this URL, you must also use the java.protocol.handler.pkgs system property to specify the security provider to use. For example:
      -keystore safkeyring://userid/ringname -Djava.protocol.handler.pkgs=com.ibm.crypto.zsecurity.provider
      End of changes for 11.0.20.1
    • A string that contains the keystore-specific safkeyringjce URL. When you use this URL, you do not need to use the java.protocol.handler.pkgs system property. For example:
      -keystore safkeyringjce://userid/ringname
      However, this format is deprecated and might be removed in a future release.
      Important: Start of changes for 11.0.20.1If you run an application that uses this URL with a security manager enabled, a circular loading error occurs. For more information, see Known issues and limitations.End of changes for 11.0.20.1
  • JCERACFKS keystore does not store passwords in the key ring, so passwords are not required to access a keystore or a private key. Therefore, the following command-line options are not supported for a JCERACFKS keystore when you use the zseckeytool command.
    • changealias
    • genseckey
    • importpass
    • keypasswd
    • storepasswd
    • printcert
    • printcertreq
  • The following options are not supported specifically for a JCERACFKS keystore:
    • keypass
    • For the importkeystore command, srckeypass and destkeypass are not supported if their target is a JCERACFKS.
    • storepass
    • For the importkeystore command, srcstorepass and deststorepass are not supported if their target is a JCERACFKS.
  • Keystore aliases are usually case-insensitive. However, certain RACF and z/OS keystores support case-sensitivity of aliases.
  • The default value for option -keyalg is RSA for JCERACFKS keystore.

Enabling the IBMZSecurity provider

Start of changes for 11.0.17.0The IBMZSecurity provider is enabled by default due to its position in the JAVA_HOME/conf/security/java.security file.End of changes for 11.0.17.0

In releases before 11.0.17.0, the IBMZSecurity provider is not enabled by default; to use it you must enable it by adding the following entry to the pre-defined list of security providers in the file JAVA_HOME/conf/security/java.security:

security.provider.2=IBMZSecurity

Renumber the list accordingly after adding an entry. The updated provider list in the java.security file after adding IBMZSecurity to the list is as shown in the following example: 

security.provider.1=OpenJCEPlus
security.provider.2=IBMZSecurity
security.provider.3=SUN
security.provider.4=SunRsaSign
security.provider.5=SunEC
security.provider.6=SunJSSE
security.provider.7=SunJCE
security.provider.8=SunJGSS
security.provider.9=SunSASL
security.provider.10=XMLDSig
security.provider.11=SunPCSC
security.provider.12=JdkLDAP
security.provider.13=JdkSASL
security.provider.14=SunPKCS11

Keystore load and update operations

To access the contents of a keystore, an application uses the load() method to retrieve the persistent data from the keystore and create a keystore object. This object can be queried and updated by the application. Keystore update methods include deleteEntry(), setEntry(), setCertificateEntry(), and setKeyEntry(). The zseckeytool update commands that are supported for JCERACFKS keystore include -certreq, -delete, -exportcert, -gencert, -genkeypair, -importcert, -importkeystore, and -list.

If the application intends to modify the persistent data for the keystore, it uses the store() method. The behavior of the store() method depends on the underlying storage of the persistent data.

JCERACFKS keystore and the keystore store() method

If a change is made to an existing keystore entry, the existing version of the entry is disconnected from the key ring. The data for the new entry is then added to the RACF database, then the new entry is connected to the key ring. Even if the update is a delete operation, whether deleteEntry() or zseckeytool -delete, the data is not removed from the RACF database. Instead, the data is only disconnected from the key ring that is represented by the keystore. To delete data from the RACF database, you must use the RACF utility RACDCERT. For more information about the command, see the z/OS version-specific documentation. For example, for version 2.4.0, see RACDCERT.

Some RACF database and key ring updates that are not allowed are as follows:

  • An entry with an expired certificate cannot be updated.
  • An entry cannot be updated with an expired certificate.
  • A certificate entry cannot be replaced with a key entry.
  • A key entry cannot be replaced with a certificate entry.
  • An entry cannot be updated unless the public key in the new version matches the public key in the existing version.
  • Although a single certificate can be connected to many key rings, only one copy of it can exist in the RACF database, and it is stored with only one label.

When the IBMZSecurity provider detects an update that is not allowed by RACF, an exception is thrown when the keystore entry update is attempted. In some cases, the IBMZSecurity security provider cannot predict that a RACF database update might be unsuccessful. One consequence of this is that a keystore update might be successful, but an error or warning is reported during the store() operation.

Some possible effects of this behavior are as follows:

  • The previous version of the entry is disconnected from the key ring and the new version is not connected to the key ring.
  • A certificate might be connected to the key ring by using a label other than the one specified in the keystore update.

If unintended and undesired changes to a keystore are found, it might be necessary to reconnect or to update key ring entries by using the RACF utility RACDCERT.

Documentation

For the IBMZSecurity API reference, see IBMZSecurity API Reference Documentation.

End of changes for 11.0.15.0