Configuring for PKCS#11 support

Configuration changes for PKCS#11 support are required in two key areas, ICSF and Java™ environment. Read on to understand both the configuration changes.

Configuration of the ICSF

Configuration of the ICSF involves configuration of ICSF Token data set (TKDS) and PKCS#11 token access control setup.

TKDS is a VSAM data set that serves as the repository for cryptographic keys and certificates that are used by PKCS#11 applications. TKDS must be set up before any z/OS® PKCS#11 applications can be run. For more information about how to set up TKDS, see z/OS Cryptographic Services ICSF Writing PKCS#11 Applications for your version of z/OS.

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 in to 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, that are as follows.

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

For more information about the SAF CRYPTOZ class resources and access levels (READ, UPDATE, or CONTROL) to one or both of these resources, see z/OS Cryptographic Services ICSF Writing PKCS#11 Applications for your version of z/OS.

In addition to the SAF CRYPTOZ class resources, ICSF performs 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 by using 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 of the Java environment

Configuration changes to the Java environment for the SunPKCS11 provider include adding the SunPKCS11 provider to the list of security providers in the $JAVA_HOME/conf/security/java.security file and creating a SunPKCS11 configuration file. A sample of the java.security file and the SunPKCS11 configuration file are shown in the following example.

Note:
  • When the configuration file is specified on the SunPKCS11 line of the provider list, the SunPKCS11 provider is automatically initialized with the information in it as part of the JVM loading the provider.
  • The SunPKCS11 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=OpenJCEPlus
security.provider.2=SUN
security.provider.3=SunRsaSign
security.provider.4=SunEC
security.provider.5=SunJSSE
security.provider.6=SunJCE
security.provider.7=SunJGSS
security.provider.8=SunSASL
security.provider.9=XMLDSig
security.provider.10=SunPCSC
security.provider.11=JdkLDAP
security.provider.12=JdkSASL
security.provider.13=SunPKCS11-PKCS11Config  <path>/pkcs11.cfg
SunPKCS11 Configuration file pkcs11.cfg
name = PKCS11Config
 library = /usr/lpp/pkcs11/lib/csnpca64.so
 description = z/OS PKCS#11 Configuration
 tokenLabel = PKCS11Config
Note: The "name" attribute is concatenated with "SunPKCS11-" to produce the provider's instance name. For example, -
// Get the SunPKCS11 provider whose PKCS#11 config file attribute name is PKCS11Config
         p = Security.getProvider("SunPKCS11-PKCS11Config");

For more information about the attributes in the SunPKCS11 configuration file, see SunPKCS11 Reference Guide.

Several items specific to the z/OS SunPKCS11 configuration file are as listed here.

  • For z/OS, the "library" attribute can be specified in either of the following two ways:
    • By specifying the Unix System Services(USS) or zFS absolute path name of the z/OS UNIX PKCS#11 DLL file. For 64-bit mode, the XPLINK DLL file name is csnpca64.so. For example, if the DLL were installed in /usr/lpp/pkcs11/lib, the absolute path name would be specified as /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 SunPKCS11 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 that contains the ICSF C API DLL. 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 SunPKCS11 provider. The beginning double slash ("//") is required. The DLL member name is case-insensitive. z/OS loads the DLL by name, according to the MVS load library search order (in order: STEPLIB/JOBLIB, LPA, and Link List).
    • Examples:
      1. library = /usr/lpp/pkcs11/lib/csnpca64.so
      2. library = //csnpca64
  • It is recommended that the tokenLabel attribute be used instead of using either the slot or slotListIndex attribute. 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 can change from one SunPKCS11 application invocation to another. For example, token TokenA exists on slot number 5 today but might be in slot number 2 tomorrow. Assuming that 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 SunPKCS11 application, the token may reside in a different slot. Therefore, using either the slot or slotListIndex attribute may cause a SunPKCS11 application to fail.

Creation of a new empty token is required before a SunPKCS11 application can be run. Token creation can be done by using the RACF® RACDCERT command with the ADDTOKEN parameter or the System SSL gskkyman program. Information is available in the following sections of the z/OS v2.5 documentation. Refer to corresponding documents for your version of z/OS.

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 the CRYPTOZ resource and how it is used by ICSF, see z/OS Cryptographic Services ICSF Writing PKCS#11 Applications for your version of z/OS.