z/OS IBMPKCS11Impl Guide

(last updated February, 2013)



Table of Contents

Overview

Beginning with SDK 6.0, Public Key Cryptographic Standards #11 (PKCS#11) is implemented on Java for z/OS using the IBMPKCS11Impl provider. This provider uses the Java Cryptography Extension (JCE) and Java Cryptography Architecture (JCA) frameworks to add the capability to use hardware cryptographic devices via PKCS#11 interfaces. The IBMPKCS11Impl provider API specification and reference document and the supported IBMPKCS11Impl public classes and methods are on IBM's developerWorks web site. Refer to the Java Security information page for more information on the PKCS#11 Implementation Provider.

The IBMPKCS11Impl provider uses Integrated Cryptographic Services Facility (ICSF) that includes the PKCS#11 C language application programming interfaces (C APIs) on z/OS for its implementation of the PKCS#11 standard. Information regarding the ICSF PKCS#11 support is primarily available in z/OS Cryptographic Services Integrated Cryptographic Services Facility Writing PKCS#11 Applications (PDF, 428.15KB), SA23-2231. Other publications such as the z/OS Cryptographic Services Integrated Cryptographic Services Facility Administrator's Guide (PDF, 2.12MB), SA22-7521 also contain information about PKCS#11 on z/OS. See the z/OS library.

Several important items to be aware of are:

Configuring the PKCS#11 Support

Configuration changes for PKCS#11 are required in two main areas. They are:

The TKDS is a VSAM data set that serves as the repository for cryptographic keys and certificates used by PKCS#11 applications. This must be set up before any z/OS PKCS#11 applications can be run. See z/OS Cryptographic Services Integrated Cryptographic Services Facility Writing PKCS#11 Applications (PDF, 428.15KB), SA23-2231 for details.

PKCS#11 token access control setup is required on z/OS. On the non-z/OS platforms, access to token information is granted based on the knowledge of a PIN and it is a requirement that a user log into a device to access the private information on a token such as private keys and secret keys. On z/OS, the PKCS#11 support does not require a user to login and logout as the PKCS#11 token access is controlled by two SAF CRYPTOZ Class resources. They are:

Further details about the SAF CRYPTOZ Class resources and access level (READ, UPDATE, or CONTROL) to one or both of these resources are documented in z/OS Cryptographic Services Integrated Cryptographic Services Facility Writing PKCS#11 Applications (PDF, 428.15KB), SA23-2231.

In addition to the SAF CRYPTOZ Class resources, ICSF will perform access control checks on the underlying PKCS#11 callable services if the CSFSERV class is active. This is similar to the way ICSF controls the access to keys and services via the CSFKEYS and CSFSERV classes. The user must have READ access to appropriate CSFSERV class resource for the Java PKCS#11 support. These include:

Configuration changes to the Java environment for the IBMPKCS11Impl provider include adding the IBMPKCS11Impl provider to the list of security providers in the $JAVA_HOME/lib/security/java.security file and creating a IBMPKCS11Impl configuration file. A sample of the Java security file and Java IBMPKCS11Impl configuration file are shown below. Several items to note are:

Provider list from the java.security file

security.provider.1=com.ibm.jsse2.IBMJSSEProvider2
security.provider.2=com.ibm.crypto.hdwrCCA.
   provider.IBMJCECCA
security.provider.3=com.ibm.crypto.pkcs11impl.
   provider.IBMPKCS11Impl /home/dan/dan1.cfg
security.provider.4=com.ibm.crypto.provider.IBMJCE
security.provider.5=com.ibm.security.jgss.IBMJGSSProvider
security.provider.6=com.ibm.security.cert.IBMCertPath 
security.provider.6=com.ibm.security.sasl.IBMSASL

IBMPKCS11Impl Configuration file (dan1.cfg)

name = DAN1
library= /usr/lpp/pkcs11/lib/csnpca3x.so
description=Dan1 config 
tokenLabel=DAN1

Note that the "name" attribute is concatenated with "IBMPKCS11Impl-" to produce the provider's instance name (see example testDan1A shown in this document).

Descriptions of the attributes in the IBMPKCS11Impl configuration file are shown in the IBMPKCS11Impl provider API specification and reference document on the IBM developerworks web site. Several items specific to z/OS are:

For more information on IBMPKCS11Impl configuration file and attributes supported, refer to the sections titled "Configuring and Using Hardware Cryptographic devices" and "Appendix C: PKCS11 Usage Tips" in the IBM Java PKCS 11 Implementation Provider 1.1 API Specification & Reference.

Creation of a new empty token is required before a Java IBMPKCS11Impl application can be run. Token creation can be done using the RACF RACDCERT command with the ADDTOKEN parameter or the System SSL gskkyman program. See z/OS Security Server RACF Command Language Reference (PDF, 3.28MB), SA22-7687 and z/OS Security Server RACF Security Administrator's Guide (PDF, 5.57MB), SA22-7683 for RACDCERT information; see z/OS Cryptographic Services System Secure Sockets Layer Programming (PDF, 2.09MB), SC24-5901 for gskkyman information. In addition, a token can be created using ICSF ISPF panels for PKCS#11. See z/OS Cryptographic Services Integrated Cryptographic Services Facility Administrator's Guide (PDF, 2.12MB), SA22-7521.

The decision on whether to create clear or secure PKCS#11 keys happens during key creation. ICSF introduced a new CRYPTOZ resource in web deliverable #12, CLEARKEY.token-label, that controls the policy on clear and secure key creation. For more information on this CRYPTOZ resource and how it is being used by ICSF, please refer to z/OS Cryptographic Services Integrated Cryptographic Services Facility: Writing PKCS #11 Applications (PDF,256KB), SA23-2231.

Initializing the IBMPKCS11Impl Provider

The recommended way on z/OS to initialize the IBMPKCSImpl provider is to use the IBMPKCS11Impl configuration file.

A sample program where the IBMPKCS11Impl configuration file is included on the IBMPKCS11Impl line in the list of security providers in $JAVA_HOME/lib/security/java.security is shown below. Note that a PKCS#11 session is created and initialized with the PKCS#11 configuration file information when the JVM loads the IBMPKCS11Impl provider.

public class testDan1A {
    public static void main(String argv[]) {
        Provider p = null;
        
        // Get the IBMPKCS11Impl provider whose PKCS#11  
        // config fileattribute name is DAN1
           p = Security.getProvider("IBMPKCS11Impl-DAN1");

        // Your Java IBMPKCS11Impl program goes here

        // Remove and close the PKCS#11 session for 
           IBMPKCS11Impl-DAN1
        ((com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl)p).
            removeSession();
    }
}

A sample program using the IBMPKCS11Impl configuration file to initialize the IBMPKCS11Impl provider programmatically is shown below. This is required in the case when no Java PKCS#11 configuration file is specified on the IBMPKCS11Impl line of the java.security provider list.

public class testDan1B {
    public static void main(String argv[]) {
        Provider p = null;

        // Get the un-initialized IBMPKCS11Impl provider 
        p = Security.getProvider("IBMPKCS11Impl");

        try {
            // Create a PKCS#11 session and initialize it  
            // using the /home/dan/dan1.cfg PKCS#11 
            // configuration file
            ((com.ibm.crypto.pkcs11impl.provider.
                IBMPKCS11Impl)p).Init( 
            "/home/dan/dan1.cfg", null);
        } catch (Exception ex) {
            System.out.println(ex.getMessage());
            System.exit(1);
        }

        // Your Java IBMPKCS11Impl program goes here

        // Remove and close the PKCS#11 session for 
        // IBMPKCS11Impl
        ((com.ibm.crypto.pkcs11impl.provider.
            IBMPKCS11Impl)p).removeSession();
    }
}

A sample program shown below that calls the IBMPKCS11Impl constructor and passing in the IBMPKCS11Impl configuration file is another way to initialize the IBMPKCS11Impl provider programmatically.

public class testDan1C {
    public static void main(String argv[]) {
        IBMPKCS11Impl p = null;
        String configFileName = "/home/dan/dan1/cfg";

        try {
            // Create new instance of the IBMPKCS11Impl 
            // provider. This constructor calls the Init 
            // method to create a PKCS#11 session 
            // and initialize it using the  
            // /home/dan/dan1.cfg PKCS#11 
            // configuration file
            p = new IBMPKCS11Impl(configFileName);
        } catch (Exception ex) {
            System.out.println(ex.getMessage());
            System.exit(1);
        }

        // Your Java IBMPKCS11Impl program goes here

        // Remove and close the PKCS#11 session 
        // for IBMPKCS11Impl
        ((com.ibm.crypto.pkcs11impl.provider.
            IBMPKCS11Impl)p).removeSession();
    }
}

Java algorithms supported by the z/OS IBMPKCS11Impl Provider

The following list shows the Java algorithms supported by the z/OS IBMPKCS11Impl Provider. The z/OS IBMPKCS11Impl Provider will only support those algorithms which are provided through services implemented by the z/OS Integrated Cryptographic Service Facility (ICSF). ICSF supported algorithms are described in z/OS Cryptographic Services Integrated Cryptographic Services Facility Writing PKCS#11 Applications (PDF, 428.15KB), SA23-2231. The z/OS IBMPKCS11Impl Provider will throw an exception for algorithms that are not supported.

Managing an X509 certificate and private key in the ICSF PKCS11 token database

Managing a X509 certificate and a private key in the ICSF PKCS#11 token data set can be done using System SSL's gskkyman, RACF's RACDCERT command, and hwkeytool. Further details about hwkeytool are available in hwkeytool - Key and Certificate Management Tool. Further details about the RACDCERT command are available in z/OS Security Server RACF Command Language Reference (PDF, 3.28MB), SA22-7687 and z/OS Security Server RACF Security Administrator's Guide (PDF, 5.57MB), SA22-7683; further details about the gskkyman are available in z/OS Cryptographic Services System Secure Sockets Layer Programming (PDF, 2.09MB), SC24-5901. In addition, the ICSF ISPF panels for PKCS#11 provide the capability to view objects such as an X509 certificate or private key object in the TKDS and make limited updates to them. See z/OS Cryptographic Services Integrated Cryptographic Services Facility Administrator's Guide (PDF, 2.12MB), SA22-7521.

From a Java programming perspective, the com.ibm.crypto.ibmpkcs11impl.provider.PKCS11KeyStore class in the IBMPKCS11Impl provider is supported. This class allows a Java application access to the ICSF PKCS#11 token data set through a set of java.security.KeyStore methods. The constructors and methods supported in the PKCS11KeyStore class are documented on IBM's developerworks website. The Java tools ikeyman and ikeycmd (the command line version of ikeyman) that may be used to manage PKCS#11 tokens and objects on other platforms are not supported on z/OS.

Using secure PKCS#11 keys with the IBMJCECCA provider

In addition to supporting secure PKCS#11 keys in web deliverable #12 to take advantage of the Crypto Express4 Enterprise PKCS#11 coprocessor, Integrated Cryptographic Services Facility (ICSF) also added some limited CCA callable services support for secure PKCS#11 keys. The two ICSF CCA callable services that were updated to support secure PKCS#11 keys are CSNDDSG (Digital Signature Sign) and CSNDPKD (Private Key Decrypt). For more information on these and other CCA callable services that ICSF supports, refer to the z/OS Cryptographic Services ICSF Application Programmer's Guide (PDF,4.9MB), SA22-7522.

The IBMJCECCA provider utilizes both CSNDDSG and CSNDPKD callable services in its cryptographic application programming interfaces (API) for creating digital signatures and for decryption/unwrap. These IBMJCECCA APIs have been updated in IBM Java Technology Edition, V7.1, to support secure PKCS#11 keys. Specifically, secure PKCS#11 RSA and Elliptic Curve private keys are now supported for digital signature generation through the IBMJCECCA Signature API, and secure PKCS#11 RSA private keys are now supported by the IBMJCECCA Cipher API for decryption and unwrap operations. For more information on the IBMJCECCA provider, refer to Java Cryptography Extension in Java Platform Standard Edition, Hardware Cryptography IBMJCECCA Overview.

Restrictions / Considerations when using the IBMPKCS11Impl provider on z/OS


Browse z/OS