JCEHYBRIDRACFKS KeyStore Implementation

The IBMJCEHYBRID provider contains a KeyStore implementation called JCEHYBRIDRACFKS. This keystore allows you to load a single SAF keyring as both a JCECCARACFKS keystore representation (which is implemented by the IBMJCECCA provider) and a JCERACFKS keystore representation (which is implemented by the IBMZSecurity provider).

Note that you must add the IBMZSecurity provider to the security provider list to use the JCERACFKS keystore. Otherwise, the JCEHYBRIDRACFKS is not properly configured.

During JVM initialization, the Java™ Security Framework loads each security provider that is listed in the java.security provider list. When a provider initializes itself, it registers with the Java Security Framework for each serviceType.algorithm that it can perform. If an application requests cryptographic services without specifying a security provider, the Java Security Framework selects the first provider in the security provider list that registered the requested service.

When a SAF keyring is loaded as a JCEHYBRIDRACFKS keystore the keyring will be loaded as both a JCECCARACFKS and a JCERACFKS keystore. The key material from both of these keystores will be combined together and represented by the JCEHYBRIDRACFKS keystore. The various pieces that are to be available by the user of the JCEHYBRIDRACFKS keystore can be described by the following tables. For each keyring being loaded, the relevant table shows the results of what will be available when ICSF is turned on and no errors occur during loading of the keystore, and the results of what will be available when ICSF is turned off or errors occur during loading of the keystore.

Note that any certificates/keys in the table ending with the name CCA have their key material located within ICSF. Additionally, IBMZSecurity private key means a key derived by IBMZSecurity by either SUN, SunRsaSign, and OpenJCEPlus providers.

Keyring without CCA

A sample of a loaded keyring that does not have CCA is as follows:

Ring: >Keyring<

Certificate   Cert Owner     USAGE       DEFAULT
-------------------------------------------------
JayCa         ID(G910501)   CERTAUTH     NO
JayEndUser    ID(G910501)   PERSONAL     YES
Keystore entries and the keystore contents that will be available when ICSF is turned on or off are as follows:
Keystore Entries Keystore Contents Available - ICSF Turned On (During Load) Keystore Contents Available - ICSF Turned Off (During Load)
JayCa entry
  • Certificate
  • Certificate
JayEndUser entry
  • Certificate
  • Certificate chain
  • IBMJCECCA private key
  • IBMZSecurity private key
  • Certificate
  • Certificate chain
  • IBMZSecurity private key
Keyring with CCA

A sample of a loaded keyring that has CCA is as follows:

Ring: >KeyringCCA<

Certificate   Cert Owner     USAGE       DEFAULT
-------------------------------------------------
JayCaCCA      ID(G910501)   CERTAUTH     NO
JayEndUserCCA ID(G910501)   PERSONAL     YES
Keystore entries and the keystore contents that will be available when ICSF is turned on or off are as follows:
Keystore Entries Keystore Contents Available - ICSF Turned On (During Load) Keystore Contents Available - ICSF Turned Off (During Load)
JayCaCCA entry
  • Certificate
  • Certificate
JayEndUserCCA entry
  • Certificate
  • Certificate chain
  • IBMJCECCA private key
Alias will be unavailable since ICSF is down and key resides in ICSF
Mixed keyring

A sample of a loaded mixed keyring is as follows:

Ring: >KeyringMix<

Certificate   Cert Owner     USAGE       DEFAULT
-------------------------------------------------
JayCa         ID(G910501)   CERTAUTH     NO
JayEndUser    ID(G910501)   PERSONAL     NO
JayCaCCA      ID(G910501)   CERTAUTH     NO
JayEndUserCCA ID(G910501)   PERSONAL     YES
Keystore entries and the keystore contents that will be available when ICSF is turned on or off are as follows:
Keystore Entries Keystore Contents Available - ICSF Turned On (During Load) Keystore Contents Available - ICSF Turned Off (During Load)
JayCa entry
  • Certificate
  • Certificate
JayEndUser entry
  • Certificate
  • Certificate chain
  • IBMJCECCA private key
  • IBMZSecurity private key
  • Certificate
  • Certificate chain
  • IBMZSecurity private key
JayCaCCA entry
  • Certificate
  • Certificate
JayEndUserCCA entry
  • Certificate
  • Certificate chain
  • IBMJCECCA private key
Alias will be unavailable since ICSF is down and key resides in ICSF.

When loaded, the new JCEHYBRIDRACFKS will contain a combination of the key and certificate material from both the JCECCARACFKS and JCERACFKS keystore representations of the same SAF keyring. This combination will be stored in a key container which contains all of the available key material from both keystores. It should be noted that IBMZSecurity does not generate keys itself but fetches keys from the SUN, SunRsaSign, and OpenJCEPlus providers for the DSA, RSA, and EC algorithms respectively. Please see the IBMJCECCA documentation titled z/OS® Unique Considerations for more information regarding the JCECCARACFKS and JCERACFKS keystores.

KeyStore operations that create new entries or update existing entries will accept either a key derived by the IBMZSecurity provider or a key derived from the IBMJCECCA provider and will store them in the instance of the JCEHYBRIDRACFKS keystore along with inserting them into the underlying keystore of choice. Keys derived from the IBMJCECCA provider will be inserted into the underlying JCECCARACFKS keystore, keys derived by the IBMZSecurity provider will be inserted into the underlying JCERACFKS keystore. Note that IBMZSecurity does not generate keys itself but fetches keys from the SUN, SunRsaSign, and OpenJCEPlus providers for the DSA, RSA, and EC algorithms respectively.

KeyStore operations that return key entries will return a new private key called HybridRACFPrivateKey. KeyStore operations that return generic certificate objects will return certificates. This means that the exact nature of the key or certificate returned by KeyStore APIs (getKey(), getCertificate(), and getCertificateChain()) does not always need to be known to the application. The HybridRACFPrivateKey or certificate can be retrieved and passed to an instance of the crypto API as a generic Key or Certificate object. That being said only cipher and signature instances derived from the IBMJCEHYBRID provider will be able to make use of the new HybridRACFPrivateKey object for RSA signature and cipher operations.

An alternative to using the cipher and signature operations in the IBMJCEHYBRID provider is to extract software JCE or IBMJCECCA implementations from the HybridRACFPrivateKey and use those implementations with the software JCE or IBMJCECCA providers. The HybridRACFPrivateKey key implementations that are returned from the JCEHYBRIDRACFKS keystore can potentially contain both the software JCE and IBMJCECCA representations of the same key. You can decide to fetch one or the other representation for use with the software JCE or IBMJCECCA providers. For example, the following code snippet extracts the software JCE representation of the HybridRACFPrivateKey and uses the SunRsaSign API to encrypt and decrypt a piece of data. Note that you can also use the OpenJCEPlus or SUN provider as the provider for instantiating the cipher object in this example.

HybridRACFInputStream his = new HybridRACFInputStream(userid, keyring, passwordChars);
KeyStore ks = KeyStore.getInstance("JCEHYBRIDRACFKS","IBMJCEHYBRID");
ks.load(his,passwordChars);

HybridRACFPrivateKey privKey = (HybridRACFPrivateKey)ks.getKey(alias,passwordChars);
PublicKey pubKey = (PublicKey)ks.getCertificate(alias).getPublicKey();

//Encrypt with SunRsaSign
Cipher cipher = Cipher.getInstance("RSA", "SunRsaSign");
cipher.init(Cipher.ENCRYPT_MODE, pubKey);
byte[] cipherText = cipher.doFinal(plainText);

//Decrypt with SunRsaSign
cipher.init(Cipher.DECRYPT_MODE, privKey.getSoftwareJCEPrivateKey());
byte[] decipheredText = cipher.doFinal(cipherText);

When you call the store() method of the JCEHYBRIDRACFKS keystore, the code attempts to write all entries back to the specified SAF keyring. All entries with keys that are derived from software JCE providers are stored as if they were inserted from a JCERACFKS KeyStore. All entries with keys that are derived from the IBMJCECCA provider are stored as if they were inserted from a JCECCARACFKS KeyStore.

A URL handler exists to allow the URL class to open the JCEHYBRIDRACFKS keystore.

The following URL strings are supported.
safkeyring

When you use this URL, you must also specify the java.protocol.handler.pkgs system property. This property enables the URLStreamHandler class to create a RACFInputStream object. The safkeyring URL and associated classes access data that is stored in a SAF (RACF®) key ring.

The value of the system property is the provider that you are using for cryptographic support. For example, if you are using the IBMJCECCA provider, set the system property as shown in this example:

java.protocol.handler.pkgs=com.ibm.crypto.hdwrCCA.provider
You can also set this property in a Java application, by using the java.lang.System.setProperty method:
System.setProperty("java.protocol.handler.pkgs", "com.ibm.crypto.hdwrCCA.provider");
If you use the safkeyring URL but you do not set the java.protocol.handler.pkgs system property, the following error occurs:
java.net.MalformedURLException: unknown protocol: safkeyring
Use the following syntax to specify the key ring and user ID:
"safkeyring://userid/keyring"
safkeyringjce | safkeyringjcehybrid | safkeyringjcecca

Support for these URLs was added in version 11 but is deprecated and might be removed in future releases.

Use the URL that corresponds with the type of RACF keystore that you want to access, as shown in the following table. You do not need to specify the java.protocol.handler.pkgs system property.
Table 1. SAF key ring URLs for different keystore types
Keystore type URL
JCECCARACFKS safkeyringjcecca
JCERACFKS safkeyringjce
JCEHYBRIDRACFKS safkeyringjcehybrid
Use the following syntax to specify the key ring and user ID for a keystore of type JCECCARACFKS:
"safkeyringjcecca://userid/keyring"

If you run an application that uses these URLs with a security manager enabled, a circular loading error occurs. For more information, see Known isues and limitations.

For more information about the IBMJCEHYBRIDRACF keystore and key objects that are included in the IBMJCEHYBRID provider, see the API documentation for the following classes:
  • com.ibm.crypto.ibmjcehybrid.provider.HybridRACFInputStream
  • com.ibm.crypto.ibmjcehybrid.provider.HybridRACFKeyStore
  • com.ibm.crypto.ibmjcehybrid.provider.HybridRACFOutputStream
  • com.ibm.crypto.ibmjcehybrid.provider.HybridRACFPrivateKey
  • com.ibm.crypto.ibmjcehybrid.provider.safkeyring.Handler