Configuring and using the IBMJCECCA provider

To use the IBMJCECCA provider, you must install and configure a hardware cryptographic device, install and run the Integrated Cryptographic Service Facility (ICSF), grant CSFSERV access permissions, and install the IBMJCECCA provider. You can retrieve error codes from the application to help you troubleshoot errors.

Configuring and using hardware cryptographic devices on IBM Z hardware

To use a hardware cryptographic device, the appropriate card must be installed and configured according to the specifications that are provided with the card. On some platforms, the user or application must set up the cryptographic environment and provide access control (for example, logging in to the card).

ICSF

On the z/OS® operating system, access to hardware cryptographic devices is controlled by the ICSF. The ICSF product provides IBM Common Cryptographic Architecture (CCA) interfaces to hardware devices. ICSF must be configured and running before the hardware cryptographic device is accessed. For more information about ICSF see z/OS Cryptographic Services for your version of z/OS. In particular, see the following sections:

  • Cryptographic Services ICSF Overview
  • ICSF System Programmers Guide
  • ICSF Administrator's Guide
  • ICSF Application Programmer's Guide

CSFSERV access permissions

Applications that call cryptographic operations through the IBMJCECCA provider require RACF® access permissions to be granted to the exploiter. The permission type depends on the services that the operations are using in the underlying ICSF code. When an application calls cryptographic services that are provided by ICSF through the IBMJCECCA provider, the CSFSERV access permissions that are listed in the following table must be granted for those services to the application's user ID.

The following table lists the ICSF APIs that are called by the IBMJCECCA provider and the required CSFSERV access permission for each of these ICSF calls.
Table 1. The ICSF APIs that are called by the IBMJCECCA provider and the associated CSFSERV access permission
ICSF APIs in JCECCA ICSF API Description-> CSFSERV Access[Access Description]
CSFIQF & CSFIQF6 (64-bit) ICSF Query Facility-> CSFIQF [ICSF Query Facility callable service]
CSNBSYE & CSNESYE (64-bit) Symmetric Key Encipher-> CSFENC [encipher callable service]-> CSFCVE [cryptographic variable encipher callable]
CSNBSYD & CSNESYD (64-bit) Symmetric Key Decipher-> CSFDEC [decipher callable service]
CSNBSAE & CSNESAE (64-bit) Symmetric Algorithm Encipher-> CSFSAE [symmetric algorithm encipher callable service]
CSNBSAD & CSNESAD (64-bit) Symmetric Algorithm Decipher-> CSFSAD [symmetric algorithm decipher callable service]
CSNBOWH & CSNEOWH (64-bit) One-Way Hash Generate-> CSFOWH [one-way hash generate callable service]
CSNBRNG & CSNERNG (64-bit) Random Number Generate-> CSFRNG [random number generate callable service]
CSNBRNGL & CSNERNGL (64-bit) Random Number Generate Long-> CSFRNGL [random number generate long callable service]
CSNBT31I & CSNET31I (64-bit) TR-31 import callable service-> CSFT31I [TR-31 import]
CSNBT31X & CSNET31X (64-bit) TR-31 export callable service-> CSFT31X [TR-31 export]
CSNDKRC & CSNFKRC (64-bit) PKDS Record Create-> CSFPKRC [PKDS record create callable service]-> CSFKRC [key record create callable service]
CSNDKRD & CSNFKRD (64-bit) PKDS Record Delete-> CSFPKRD [PKDS record delete callable service]-> CSFKRD [key record delete callable service]
CSNDRKD & CSNFRKD (64-bit) Retained Key Delete-> CSFRKD [retained key delete callable service]
CSNDPKG & CSNFPKG (64-bit) PKA Key Generate-> CSFPKG [PKA key generate callable service]
CSNDDSG & CSNFDSG (64-bit) Digital Signature Generate-> CSFDSG [digital signature generate service]
CSNDDSV & CSNFDSV (64-bit) Digital Signature Verify-> CSFDSV [digital signature verify callable service]
CSNDPKB & CSNFPKB (64-bit) PKA Key Token Build-> CSFPKG [PKA key generate callable service]-> CSFPKT [PKA key token change callable service]
CSNDRKL & CSNFRKL (64-bit) Retained Key List-> CSFRKL [retained key list callable service]
CSNDPKX & CSNFPKX (64-bit) PKA Public Key Extract-> CSFPKX [PKA Public Key Extract callable service]
CSNBENC & CSNEENC (64-bit) Encipher-> CSFENC [encipher callable service]
CSNBDEC & CSNEDEC (64-bit) Decipher-> CSFDEC [decipher callable service]
CSNDPKE & CSNFPKE (64-bit) PKA Encrypt-> CSFPKE [PKA encrypt callable service]
CSNDPKD & CSNFPKD (64-bit) PKA Decrypt-> CSFPKD [PKA decrypt callable service]]
CSNDPKI & CSNFPKI (64-bit) PKA Key Import-> CSFPKI [PKA key import callable service]
CSNBCKM & CSNECKM (64-bit) Multiple Clear Key Import-> CSFCKM [multiple clear key import callable service]
CSNBKGN & CSNEKGN (64-bit) 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 (64-bit) ECC Diffie-Hellman-> CSFEDH [ECC Diffie-Hellman callable service]
CSNBKTB & CSNEKTB (64-bit) Key Token Build-> CSFKTB [key token build callable service]
CSNBKGN2 & CSNEKGN2 (64-bit) Key Generate2-> CSFKGN2 [key generate2 callable service]
CSNBKEX & CSNEKEX (64-bit) Key Export-> CSFKEX [key export callable service]
CSNBKIM & CSNEKIM (64-bit) Key Import-> CSFKIM [key import callable service]
CSNDSYI2 & CSNFSYI2 (64-bit) Symmetric Key Import2-> CSFSYI2 [symmetric key import2 callable service]
CSNBKTR2 & CSNEKTR2 (64-bit) Key Translate2-> CSFKTR2 [key translate2 callable service]
CSNBKRC2 & CSNEKRC2 (64-bit) Key Record Create2-> CSFKRC2 [key record create2 callable service]
CSNBKRR2 & CSNEKRR2 (64-bit) Key Record Read2-> CSFKRR2 [key record read2 callable service]
CSNBHMG & CSNEHMG (64-bit) HMAC Generate-> CSFHMG [HMAC generate callable service]

Installing the IBMJCECCA provider

To use the IBMJCECCA provider, you specify it either statically, by updating the java.security file, or dynamically in your Java™ application code. For more information, see Installing security providers.

You must install and start ICSF before attempting to use the IBMJCECCA provider. For more information, see the z/OS Cryptographic Services ICSF Administrator's Guide for your version of z/OS. If IBM®JCECCA is used and ICSF is not started or the IBM PCIe Cryptographic Coprocessor software is not installed, some cryptographic operations might fail.

Disable IBMJCECCA initialization

If ICSF is not enabled or started on the system, and a provider exception occurs, use one of the following two solutions to resolve the issue.
  • Remove IBMJCECCA from the provider list in the java.security file.
  • Use the ibmjcecca.disable=YES property to remove it from use. Set this property while using the java command as shown here.
    java -Dibmjcecca.disable=YES -Djava.security.debug=all

    When running the Java application, the IBMJCECCA trace message is displayed, which reads as follows: IBMJCECCA is disabled via property ibmjcecca.disable. When IBMJCECCA is disabled by using this method, the provider does not initialize and does not perform any service.

CCA API error codes

When calls are made by the IBMJCECCA provider to CCA services to perform cryptographic operations, return codes are displayed in error messages by using the decimal values of the error codes. The codes are documented in the z/OS Cryptographic Services ICSF Application Programmer's Guide with further detail in IBMJCECCA hardware errors.

An application can retrieve error data from the CCA call by using the JCECCARuntimeException class. The class includes methods to retrieve the following data from the CCA API call:
  • The name of the CCA API call that threw the exception
  • The exception message that was generated by the IBMJCECCA provider
  • The CCA API call return code, in decimal format
  • The CCA API call reason code, in decimal format
The following example shows how an application can catch this exception and display CCA API call data:
catch (Exception e) {
    if (e instanceof JCECCARuntimeException) {
             JCECCARuntimeException jcre = (JCECCARuntimeException)e;
                System.err.println("API name: " + jcre.getAPIName());
                System.err.println("Message: " + jcre.getExceptionMessage());
                System.err.println("RC: " + jcre.getReturnCode());
                System.err.println("RS: " + jcre.getReasonCode());
    }
    e.printStackTrace();