Java Cryptography Extension in Java Platform Standard Edition, Hardware Cryptography IBMJCECCA Overview



Table of Contents

Overview

In general, Java Cryptography Extension in the Java Platform Standard Edition (JCE in Java SE) provides a framework and implementations for encryption, key generation and key agreement, and Message Authentication Code (MAC) algorithms. Support for encryption includes symmetric, asymmetric, block, and stream ciphers. The software also supports secure streams and sealed objects.

JCE in Java SE supplements the Java platform, which already includes interfaces and implementations of message digests and digital signatures.

This IBMJCECCA implementation extends JCE seamlessly to add the capability to use hardware cryptography via the IBM Common Cryptographic Architecture (CCA) interfaces. This provider takes advantage of hardware cryptography within the existing JCE architecture and gives Java programmers the significant security and performance advantages of hardware cryptography with minimal changes to existing Java applications. Just as the complexities of hardware cryptography are taken care of within the normal Java Cryptography Architecture, IBMJCECCA makes advanced security and performance easily available using hardware cryptographic devices.

IBM CCA is a set of software elements that provide common application interfaces to secure, high-speed cryptographic services on various platforms via hardware cryptographic devices. The amount and type of hardware cryptographic services available depends on your platform and hardware device. For more information about which services are available to IBMJCECCA from the hardware cryptographic devices you have installed, refer to the z/OS ICSF Overview (PDF,545KB) (SA22-7519), Appendix B. Summary of Callable Service Support by Hardware Configuration. The service names listed in the table titled Summary of ICSF Callable Services Support in Appendix B correspond to the list of services in the section CSFSERV Access Permissions Required for ICSF Services Used by IBMJCECCA Provider.

IBMJCECCA uses hardware cryptography to implement those engine classes that can use the hardware function available through IBM CCA. Some of the JCE function will be available through this hardware implementation (IBMJCECCA) and others, those that the CCA hardware cannot perform will only be available through a software cryptography provider like IBMJCE.

IBMJCECCA provides for all the engine classes available in Java Cryptographic Extensions (JCE) including Message Digest, Signature and KeyFactory classes. This makes Message Digests available through the MD2, MD5 and SHA algorithms. It further provides digital signature and verification via the RSA, DSA and ECDSA algorithms. IBMJCECCA also includes true random number generation, key generation via key factories, key/certificate generation and key/certificate management via a keytool application. This hardware capable implementation provides the symmetric algorithms AES, DES, triple DES (also known as DESede), HMAC and PBE. It also provides the asymmetric algorithms RSA encryption and decryption with zero padding, and PKCS 1 type 2 padding.

For information on the IBMJCECCA package and classes, see the online documentation section.

Online documentation

The IBMJCECCA provider documentation follows:

For a general overview of JCE architecture, including the API specification and reference, visit Java Cryptography Extension (JCE) Web site. The documents on this Web site contain links to many other Web-based information sources.

Features of the IBMJCECCA provider

The IBMJCECCA provider package includes:

Using IBMJCECCA

To use the IBMJCECCA provider, you must specify the following in your java.security file in the ${java-home}/lib/security directory:

security.provider.1=com.ibm.crypto.hdwrCCA.provider.
   IBMJCECCA
security.provider.2=com.ibm.crypto.provider.IBMJCE

It is also necessary to start ICSF before attempting to use IBMJCECCA. If IBMJCECCA is the first JCE in your provider list and ICSF is not started some cryptographic operations may fail.

Specifying Full Function versus Limited Key Size Cryptography

Files US_export_policy.jar and local_policy.jar, in directory ${java-home}/lib/security, give you the ability to do limited function cryptography and are installed by default.

For full function cryptography you need an unrestricted policy that gives the ability to do full function cryptography. The policy files, which are the same for SDK 1.4.2, SDK 5, SDK 6, and SDK 7 may be downloaded. Replace US_export_policy.jar and local_policy.jar in the ${java-home}/lib/security directory with the new files.

Representation of ICSF Error Code Values

When calls are made by the IBMJCECCA provider to ICSF services to perform cryptographic operations, return/reason codes are displayed in error messages using the decimal values of the error codes, which are documented in the z/OS Cryptographic Services ICSF Application Programmer's Guide (PDF,3.11MB) (SA22-7522). See Appendix A for a list of Return Codes and Reason Codes from the ICSF Callable Services.

CSFSERV Access Permissions Required for ICSF Services Used by IBMJCECCA Provider

Applications invoking cryptographic operations through the IBMJCECCA provider require various RACF access permissions granted to the exploiter, based upon which services they are exercising in the underlying ICSF code. In situations where an application is invoking cryptographic services which are provided by ICSF through the IBMJCECCA provider, the CSFSERV Access Permissions listed in the table below must be granted for those services to the application userid. Also note that if an application is moved or reconfigured into an environment which will use hardware cryptographic support where it did not use that support previously (for example, it previously invoked cryptographic operations through a pure Java software provider such as IBMJCE), these permissions will be needed to permit execution of those ICSF services providing the requested cryptographic support.

The following are ICSF APIs called by IBMJCECCA provider. The CSFSERV access for each of these ICSF calls is also given below:

ICSF APIs in JCECCA ICSF API Description
-> CSFSERV Access
     [Access Description]
CSFIQF & CSFIQF6 (64bit) ICSF Query Facility
-> CSFIQF [ICSF Query Facility callable service]
CSNBSYE & CSNESYE (64bit) Symmetric Key Encipher
-> CSFENC [encipher callable service]
-> CSFCVE [cryptographic variable encipher callable]
CSNBSYD & CSNESYD (64bit) Symmetric Key Decipher
-> CSFDEC [decipher callable service]
CSNBSAE & CSNESAE (64bit) Symmetric Algorithm Encipher
-> CSFSAE [symmetric algorithm encipher callable service]
CSNBSAD & CSNESAD (64bit) Symmetric Algorithm Decipher
-> CSFSAD [symmetric algorithm decipher callable service]
CSNBOWH & CSNEOWH (64bit) One-Way Hash Generate
-> CSFOWH [one-way hash generate callable service]
CSNBRNG & CSNERNG (64bit) Random Number Generate
-> CSFRNG [random number generate callable service]
CSNBRNGL & CSNERNGL (64bit) Random Number Generate Long
-> CSFRNGL [random number generate long callable service]
CSNDKRC & CSNFKRC (64bit) PKDS Record Create
-> CSFPKRC [PKDS record create callable service]
-> CSFKRC [key record create callable service]
CSNDKRD & CSNFKRD (64bit) PKDS Record Delete
-> CSFPKRD [PKDS record delete callable service]
-> CSFKRD [key record delete callable service]
CSNDRKD & CSNFRKD (64bit) Retained Key Delete
-> CSFRKD [retained key delete callable service]
CSNDPKG & CSNFPKG (64bit) PKA Key Generate
-> CSFPKG [PKA key generate callable service]
CSNDDSG & CSNFDSG (64bit) Digital Signature Generate
-> CSFDSG [digital signature generate service]
CSNDDSV & CSNFDSV (64bit) Digital Signature Verify
-> CSFDSV [digital signature verify callable service]
CSNDPKB & CSNFPKB (64bit) PKA Key Token Build
-> CSFPKG [PKA key generate callable service]
-> CSFPKT [PKA key token change callable service]
CSNDRKL & CSNFRKL (64bit) Retained Key List
-> CSFRKL [retained key list callable service]
CSNDPKX & CSNFPKX (64bit) PKA Public Key Extract
-> CSFPKX [PKA Public Key Extract callable service]
CSNBENC & CSNEENC (64bit) Encipher
-> CSFENC [encipher callable service]
CSNBDEC & CSNEDEC (64bit) Decipher
-> CSFDEC [decipher callable service]
CSNDPKE & CSNFPKE (64bit) PKA Encrypt
-> CSFPKE [PKA encrypt callable service]
CSNDPKD & CSNFPKD (64bit) PKA Decrypt
-> CSFPKD [PKA decrypt callable service]]
CSNDPKI & CSNFPKI (64bit) PKA Key Import
-> CSFPKI [PKA key import callable service]
CSNBCKM & CSNECKM (64bit) Multiple Clear Key Import
-> CSFCKM [multiple clear key import callable service]
CSNBKGN & CSNEKGN (64bit) Key Generate
-> CSFKGN [key generate callable service]
CSNDSYI Symmetric Key Import
-> CSFSYI [symmetric key import callable service]
CSNDSYX Symmetric Key Export
-> CSFSYX [symmetric key export callable service]
CSNDEDH & CSNFEDH (64bit) ECC Diffie-Hellman
-> CSFEDH [ECC Diffie-Hellman callable service]
CSNBKTB & CSNEKTB (64bit) Key Token Build
-> CSFKTB [key token build callable service]

Browse z/OS