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:
Keystore entries and the keystore contents that will be available when ICSF is turned on or off are as follows:Ring: >Keyring< Certificate Cert Owner USAGE DEFAULT ------------------------------------------------- JayCa ID(G910501) CERTAUTH NO JayEndUser ID(G910501) PERSONAL YES
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:
Keystore entries and the keystore contents that will be available when ICSF is turned on or off are as follows:Ring: >KeyringCCA< Certificate Cert Owner USAGE DEFAULT ------------------------------------------------- JayCaCCA ID(G910501) CERTAUTH NO JayEndUserCCA ID(G910501) PERSONAL YES
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:
Keystore entries and the keystore contents that will be available when ICSF is turned on or off are 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 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.
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. Thesafkeyring
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 thesafkeyring
URL but you do not set thejava.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 thejava.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.
- 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