IBMJCECCA

The IBMJCECCA provider extends Java™ Cryptography Extension (JCE) and Java Cryptography Architecture (JCA) seamlessly to add support for hardware cryptography by using IBM Common Cryptographic Architecture (CCA) interfaces on the z/OS® operating system.

The IBMJCECCA provider implements the existing JCE architecture, taking advantage of hardware cryptography to give Java programmers the significant security and performance advantages of hardware cryptography with minimal changes to existing Java applications. Because the complexities of hardware cryptography are handled within the normal JCE APIs, the advanced security and performance of hardware cryptographic devices are made easily available.

IBM CCA is a set of software elements that provide common application interfaces to secure, high-speed cryptographic services on various platforms by using hardware cryptographic devices. On z/OS, access to hardware cryptographic devices is controlled by the Integrated Cryptographic Service Facility (ICSF). This software package provides IBM CCA interfaces to hardware devices that are used by the IBMJCECCA provider. One or more of these hardware cryptography features must be installed to use the IBMJCECCA provider.

For more information about the cryptographic features that are supported by your hardware, refer to the IBM Z® machine's reference or technical guide and your service or support organization.

The IBMJCECCA provider supports the following items:

Table 1. Algorithms supported by the IBMJCECCA provider
API Supported algorithms
Signature Algorithms DSAforSSL, SHA1withDSA*, MD2withRSA, MD5withRSA, RSAforSSL, SHA1withRSA, SHA2withRSA, SHA224withRSA, SHA3withRSA, SHA5withRSA, ECDSAforSSL, SHA1withECDSA, SHA224withECDSA, SHA2withECDSA, SHA3withECDSA, SHA5withECDSA, RSASSA-PSS, CRYSTALS-Dilithium, ML-DSA
Message Authentication Code (MAC) HmacMD2, HmacMD5, HmacSHA1, HmacSHA256, HmacSHA384, HmacSHA512, PBM
Message Digest MD2, MD5, SHA2, SHA3, SHA5, SHA
KeyFactory RSA, EC, RSASSA-PSS, DSA (Only supported on machines before the IBM 2084 eServer zSeries 900), CRYSTALS-Kyber, CRYSTALS-Dilithium,ML-KEM, ML-DSA
Key agreement ECDH
Key (pair) Generator DSA (supported on machines before the IBM 2084 eServer zSeries 900 only), AES, DESede, DES, HmacMD2, HmacMD5, HmacSHA1, HmacSHA256, HmacSHA384, HmacSHA512, CRYSTALS-Kyber, CRYSTALS-Dilithium, ML-KEM, ML-DSA
Algorithm Parameter Generator DSA (supported on machines before the IBM 2084 eServer zSeries 900 only), AES, DES, DESede, DSA, OAEP, PBE, PBM, RSASSA-PSS, EC
Algorithm Parameter DES, TripleDES, DSA (supported on machines before the IBM 2084 eServer zSeries 900 only), AES, PBEwithMD5AndDES, Certificate X.509
SecureRandom IBMSecureRandom
Keystores JCECCAKS, JCECCARACFKS, JCA4758KS
SecretKeyFactory HMACSHA1, HMACSHA224, HMACSHA256, HMACSHA384, HMACSHA512, DES, DESede, AES, PBEWithMD2AndDES, PBEWithMD5AndDES, PBEWithSHAAndDES, PBEWithSHAAndTripleDES, PBEWithSHAAnd2KeyTripleDES, PBEWithSHAAnd3KeyTripleDES, PBEWithMD2AndTripleDES, PBEWithMD5AndTripleDES, PBEWithSHAAnd2KeyTripleDES, PBEWithSHAAnd3KeyTripleDES, PKCS5Key, PBKDF1, PBKDF2
Cipher Algorithms AES, AES/CBC/NoPadding, AES/CBC/PKCS5Padding, AES/ECB/NoPadding, AES/ECB/PKCS5Padding, AESKeyWrap, DES/CBC/NoPadding, TripleDES/CBC/NoPadding, PBEWithMD2AndDES, PBEWithMD2AndTripleDES, DES, DESede, DESedeKeyWrap, DESedeTR31KeyWrap, PBEWithMD2AndDES, PBEWithMD2AndTripleDES, PBEWithMD5AndDES, PBEWithMD5AndTripleDES, PBEWithSHA1AndDES, PBEWithSHA1AndTripleDES, RSA, RSAforSSL, RSA/ECB/PKCS1Padding, RSA/SSL/PKCS1Padding, PBEWithSHAAnd2KeyTripleDES, PBEWithSHAAnd3KeyTripleDES, CRYSTALS-Kyber

Keystore support

The IBMJCECCA provider supports four keystore types: JCECCAKS, JCE4758KS, JCECCARACFKS, and JCE4758RACFKS. The JCECCARACFKS and JCE4758RACFKS keystore types are only supported on z/OS. The JCECCAKS keystore uses strong encryption (triple DES) to protect the keys when stored in a file. The JCECCARACF®KS keystore handles keys and certificates that are stored in RACF key rings. The JCE4758KS and JCE4758RACFKS keystores are included for compatibility with earlier versions. The JCECCAKS keystore extends and replaces the JCE4758KS keystore. The JCECCARACFKS keystore extends and replaces the JCE4758RACFKS keystore.

JCECCAKS supports the migration of keys from other keystores by using normal keystore interfaces. The following keys are supported by JCECCAKS keystores for migration and for storage:

  • RSAPrivateHWKey
  • DSAPrivateHWKey
  • ECPrivateHWKey
  • RSAPrivateKey
  • RSAPrivateCrtKey
  • DSAPrivateKey
  • ECPrivateKey
  • Any SecretKey

If you want to migrate a software key into a JCECCAKS hardware keystore, you can use the com.ibm.crypto.hdwrCCA.provider.WrapperKey class. An instance of this class is a wrapper that contains a software key and the hardware attributes to associate with the key when it is imported into the hardware keystore.

The following example illustrates wrapping a software key SoftwareKey, and inserting it into the okeyStore keystore:

byte storeType = KeyHWAttributeValues.PKDS;
byte keyUsage = KeyHWAttributeValues.KEYMANAGEMENT;
keyAttribs = new RSAKeyHWAttributes(storeType, keyUsage);

WrapperKey wrappedKey = new WrapperKey((java.security.PrivateKey)SoftwareKey, keyAttribs);

okeyStore.setKeyEntry(alias, wrappedKey, istorePass, certs);

Default keystore for IBMJCECCA

The default JCE keystore is named .keystore and is located in the user's home directory. The default JCECCAKS keystore is named .HWkeystore and is located in the user's home directory.

The default home directory (user.home) is /home/userid. For example, the default home directory of the U23LPTQ user is /home/U23LPTQ.