Beginning with IBM® Semeru Runtime Certified Edition for z/OS®, Version 11.0, Public Key Cryptographic Standards #11 (PKCS#11) is implemented on Java for z/OS using the SunPKCS11 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 SunPKCS11 security provider can be found in the Oracle PKCS#11 Reference Guide.
The SunPKCS11 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:
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.
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 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:
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:
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 SunPKCS11 configuration file are shown below. Several items to note are:
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
name = PKCS11Config
library = /usr/lpp/pkcs11/lib/csnpca64.so
description = z/OS PKCS#11 Configuration
tokenLabel = PKCS11Config
Note that the "name" attribute is concatenated with "SunPKCS11-" to produce the provider's instance name (see example testPKCS11A shown in this document).
Descriptions of the attributes in the SunPKCS11 configuration file are shown in the SunPKCS11 Reference Guide.
Several items specific to z/OS are:
Creation of a new empty token is required before a SunPKCS11 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:
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.
The recommended way on z/OS to initialize the PKCS11 provider is to use the SunPKCS11 configuration file.
Provider provider = Security.getProvider("SunPKCS11");
AuthProvider authProv = provider.configure(path);
Where path is the path and file name of the SunPKCS11 configuration file.A sample program where the SunPKCS11 configuration file is included on the SunPKCS11 line in the list of security providers in $JAVA_HOME/conf/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 SunPKCS11 provider.
public class testPKCS11A {
public static void main(String argv[]) {
Provider p = null;
// Get the SunPKCS11 provider whose PKCS#11
// config fileattribute name is PKCS11Config
p = Security.getProvider("SunPKCS11-PKCS11Config");
// Your Java PKCS11 program goes here
}
}
A sample program using the SunPKCS11 configuration file to initialize the SunPKCS11 provider programmatically is shown below. This is required in the case when no Java PKCS#11 configuration file is specified on the SunPKCS11 line of the java.security provider list.
public class testPKCS11B {
public static void main(String argv[]) {
Provider p = null;
AuthProvider authProv = null;
// Get the un-initialized SunPKCS11 provider
p = Security.getProvider("SunPKCS11");
try {
// Create a PKCS#11 session and initialize it
// using the /home/user/pkcs11.cfg PKCS#11
// configuration file
authProv = p.configure("/home/user/pkcs11.cfg");
} catch (Exception ex) {
System.out.println(ex.getMessage());
System.exit(1);
}
// Your Java PKCS11 program goes here
}
}
The following list shows the algorithms supported by the z/OS SunPKCS11 Provider. The z/OS SunPKCS11 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 SunPKCS11 Provider will throw an exception for algorithms that are not supported.
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. Information is available in:
Refer to the applicable z/OS release documentation, in the z/OS library.
The SunPKCS11 provider allows a Java application to access the ICSF PKCS#11 token data set through java.security.KeyStore methods.
The IBMJCECCA keystore application hwkeytool now supports PKCS11 keystores when the IBMJCECCA and SunPKCS11 providers are present in the security properties file. -keystore must be NONE if -storetype is PKCS11. The following example is how to list a PKCS11 keystore:
hwkeytool -list -storetype PKCS11 -keystore NONE
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.
attributes(generate, CKO_PUBLIC_KEY, CKK_RSA) = {
CKA_SIGN = true
}
IBM is a trademark or registered trademark of International Business Machines Corporation in the United States, or other countries, or both.
Oracle and Java are registered trademarks of Oracle and/or its affiliates.
Other company, product, or service names may be trademarks or service marks of others.
|
Copyright © 1997-2022 Oracle and/or its affiliates. All Rights Reserved. Copyright © 2022 IBM Corporation, Inc. All Rights Reserved. |