z/OS IBMPKCS11Impl Guide

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. Reference documentation for the IBMPKCS11Impl security provider can be found in the IBM Knowledge Center, IBM SDK, Java Technology Edition. Select the Java Edition (version 6.0.0 or later) -> Security Reference for IBM SDK, ... -> IBMPKCS11Impl 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 ICSF Writing PKCS#11 Applications
• z/OS Cryptographic Services ICSF Administrator's Guide
• z/OS Cryptographic Services ICSF Programmer's Guide

Refer to the applicable z/OS release documentation, in the z/OS library.

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:

• Secure key support for PKCS#11 was added in Integrated Cryptographic Services Facility (ICSF) web deliverable #12 to take advantage of the Crypto Express4 Enterprise PKCS#11 coprocessor available on zHelix machines. Prior to this addition, only clear keys were supported in the ICSF token key data set (TKDS) for PKCS#11 on z/OS, and there was no Java PKCS#11 secure key support. If you don't have the necessary hardware and software pre-requisites for PKCS#11 secure key support and require secure keys, consider using the IBMJCECCA hardware provider.
• For IBM z/OS Java technology prior to SDK 7 SR 8 (Java 7.0.8) and SDK 727 SR 2 (Java 7.1.2), support is not available in the IBMPKCS11Impl provider on z/OS for PKCS#11 hardware exploitation by the IBMJSSE2 provider. Customers requiring hardware exploitation with IBMJSSE2 should use the IBMJCECCA provider.

Back to top

Configuring the PKCS#11 Support

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

• Configuration of the ICSF token data set (TKDS) and PKCS#11 token access control setup
• Configuration changes required to the Java environment.

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 ICSF Writing PKCS#11 Applications. Refer to the applicable z/OS release documentation, in the z/OS library.

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:

• USER.token-label - Controls the User role
• SO.token-label - Controls the security officer (SO) role

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 ICSF Writing PKCS#11 Applications. Refer to the applicable z/OS release documentation, in the z/OS library.

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:

• CSF1TRC - Token or object creation
• CSF1TRD - Token or object deletion
• CSF1TRL - Token or object find
• CSF1SAV - Set object attributes
• CSF1GAV - Get object attributes
• CSF1GSK - Generate secret key
• CSF1GKP - Generate key pair
• CSF1PKS - Private key signature or decrypt
• CSF1PKV - Public key signature or encrypt
• CSF1SKD - Symmetric key decrypt
• CSF1SKE - Symmetric key encryption
• CSFOWH - One-way hash
• CSF1WPK - Wrap key
• CSF1UWK - Unwrap key

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:

• When the configuration file is specified on the IBMPKCS11Impl line of the provider list, the IBMPKCS11Impl provider is automatically initialized with the information in it as part of the JVM loading the provider.
• The IBMPKCS11Impl configuration file must reside in an OMVS directory (not in a z/OS data set).

Provider list from the java.security file

security.provider.1=com.ibm.jsse2.IBMJSSEProvider2
security.provider.2=com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl /home/user/pkcs11.cfg
security.provider.3=com.ibm.crypto.provider.IBMJCE
security.provider.4=com.ibm.security.jgss.IBMJGSSProvider
security.provider.5=com.ibm.security.cert.IBMCertPath
security.provider.6=com.ibm.security.sasl.IBMSASL
security.provider.7=com.ibm.xml.crypto.IBMXMLCryptoProvider
security.provider.8=com.ibm.xml.enc.IBMXMLEncProvider
security.provider.9=com.ibm.security.jgss.mech.spnego.IBMSPNEGO
security.provider.10=sun.security.provider.Sun

IBMPKCS11Impl Configuration file (pkcs11.cfg)

name = PKCS11Config
library = /usr/lpp/pkcs11/lib/csnpca3x.so
description = z/OS PKCS#11 Configuration
tokenLabel = PKCS11Config

Note that the "name" attribute is concatenated with "IBMPKCS11Impl-" to produce the provider's instance name (see example testPKCS11A 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 z/OS, the "library" attribute can be specified in either of two ways:
  • By specifying the HFS or zFS absolute path name of the z/OS UNIX PKCS#11 DLL file. For 31-bit mode, the XPLINK DLL file name is csnpca3x.so; for 64-bit mode, the XPLINK DLL file name is csnpca64.so. So if the DLL were installed in /usr/lpp/pkcs11/lib, the absolute path name would be specified as /usr/lpp/pkcs11/lib/csnpca3x.so for 31-bit mode, or /usr/lpp/pkcs11/lib/csnpca64.so for 64-bit mode. The non-XPLINK version of the ICSF C API DLL (csnpcapi.so) is NOT supported by the IBMPKCS11Impl provider. The beginning slash ("/") is required for the path name to be validated as an absolute path. The DLL path and file name are case-sensitive.
  • By specifying the member name of the MVS partitioned dataset containing the ICSF C API DLL. For 31-bit mode, the member name must be specified as //CSNPCA3X; for 64-bit mode, the member name must be specified as //CSNPCA64. These are the XPLINK ICSF C API DLL file names. The non-XPLINK version of the ICSF C API DLL (//CSNPCAPI) is NOT supported by the IBMPKCS11Impl provider. The beginning double slash ("//") is required. The DLL member name is case-insensitive. z/OS will load the DLL by name, according to the the MVS load library search order (in order: STEPLIB/JOBLIB, LPA, Link List). Note that the "//CSNPCA3X" or "//CSNPCA64" format are not supported for all of the deprecated techniques to initialize the IBMPKCS11Impl provider.
  • Examples:
    1. library = /usr/lpp/pkcs11/lib/csnpca3x.so
    2. library = //csnpca64

• It is strongly recommended that the tokenLabel attribute be used instead of using either the slot or slotListIndex attributes. The number of slots that a user sees and the order that they appear is dependent upon the number of tokens in the ICSF token database, the token values, and the SAF CRYPTOZ class protection profiles currently defined. The slot with which a given token is associated may change from one Java IBMPKCS11Impl application invocation to another. For example, a given token will exist on slot 5 today but be in slot 2 tomorrow. Assuming a target token is not deleted, the ICSF PKCS#11 support guarantees that the token resides in its current slot only for the life of a PKCS#11 session. If a user restarts a Java IBMPKCS11Impl application, the token may reside in a different slot. Therefore, using either the slot or slotListIndex attributes may cause a Java IBMPKCS11Impl application to fail.

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 Knowledge Center, IBM SDK, Java Technology Edition. Select the Java Edition (version 6.0.0 or later) -> Security Reference for IBM SDK, ... -> IBMPKCS11Impl Provider -> IBMPKCS11Impl Provider for Java.

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. Information is available in:

• z/OS Security Server RACF Command Language Reference for RACDCERT information
• z/OS Security Server RACF Security Administrator's Guide for RACDCERT information
• z/OS Cryptographic Services System SSL Programming for gskkyman information
• z/OS Cryptographic Services ICSF Administrator's Guide to create a PKCS#11 token using ISPF panels

Refer to the applicable z/OS release documentation, in the z/OS library.

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, see z/OS Cryptographic Services ICSF Writing PKCS#11 Applications. Refer to the applicable z/OS release documentation, in the z/OS library.

Back to top

Initializing the IBMPKCS11Impl Provider

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

• This file name can be included on the IBMPKCS11Impl provider line in the list of security providers in the $JAVA_HOME/lib/security/java.security file.
• The IBMPKCS11Impl provider can also be initialized using the configuration file name and location programmatically with the

  com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl.Init (String, char[])
  

  method. The String parameter is the full directory path and name of the configuration file; the char[] parameter is the password. On z/OS, the password parameter is ignored as the z/OS PKCS#11 support does not require a user to login into a PKCS#11 device to be authenticated.
• Programmatically calling the

  com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl(java.lang.String fullFileName)

  constructor passing in the full configuration file name is a third way to initialize the IBMPKCS11Impl provider using the 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 testPKCS11A {
    public static void main(String argv[]) {
        Provider p = null;

        // Get the IBMPKCS11Impl provider whose PKCS#11
        // config fileattribute name is PKCS11Config
           p = Security.getProvider("IBMPKCS11Impl-PKCS11Config");

        // Your Java IBMPKCS11Impl program goes here

        // Remove and close the PKCS#11 session for
        // IBMPKCS11Impl-PKCS11Config
        ((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 testPKCS11B {
    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/user/pkcs11.cfg PKCS#11
            // configuration file
            ((com.ibm.crypto.pkcs11impl.provider.
                IBMPKCS11Impl)p).Init("/home/user/pkcs11.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 testPKCS11C {
    public static void main(String argv[]) {
        IBMPKCS11Impl p = null;
        String configFileName = "/home/user/pkcs11.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/user/pkcs11.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();
    }
}

Back to top

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 ICSF Writing PKCS#11 Applications. Refer to the applicable z/OS release documentation, in the z/OS library. The z/OS IBMPKCS11Impl Provider will throw an exception for algorithms that are not supported.