Restrictions during usage of the z/OS SunPKCS11 provider

The following restrictions and conditions apply when you use the SunPKCS11 provider.

  • Java™ PKCS#11 applications that require stronger cryptography than the default strength as defined by the jurisdiction policy files in $JAVA_HOME/conf/security file must be written considering the following points.
    • Get the unrestricted policy files from this website.
    • Copy the unrestricted policy files US_export_policy.jar and local_policy.jar to $JAVA_HOME/conf/security overwriting the default strength policy files.
  • If a SunPKCS11 exception Template is inconsistent is thrown and the attributes option in the SunPKCS11 configuration file are set, verify that the attributes are compatible. For example, a Template is inconsistent exception is thrown when the public or private RSA key pair is generated. The following attributes are set in the SunPKCS11 configuration file.
    attributes(generate, CKO_PUBLIC_KEY, CKK_RSA) = {
               CKA_SIGN = true
}
    Note: This example causes the exception because the CKA_SIGN attribute is normally associated with an RSA private key.
  • If an exception is thrown that includes the string Vendor defined error, the bad code that is displayed is an ICSF return code and reason code. It is in the format 0x'pxxxyyyy' where xxx is the ICSF return code and yyyy is the ICSF reason code (the p value can be ignored). To determine the meaning of these codes, see z/OS® Cryptographic Services ICSF Application Programmer's Guide for your version of z/OS.
  • If the Vendor defined error exception's return code is 0xc00c008, it might be due to a generated RSA private key that has a longer Modulus Exponent than permitted. If so, the size of Modulus Exponent is limited to 1024 bits in your z/OS hardware cryptographic environment. To determine the permitted sizes for a Modulus Exponent, see z/OS Cryptographic Services ICSF Writing PKCS#11 Applications for your version of z/OS. Refer to the Key types and mechanisms supported section.

    The exception might be resolved by using one of the following ways:

    1. Programmatically define the size of the Modulus Exponent to a permitted size.
    2. Activate a z/OS hardware cryptographic accelerator card; in this case, contact your system administrator.
    Note: Generate z/OS PKCS #11 RSA private keys in Chinese Remainder Theorem (CRT) format. They circumvent this exception and normally perform better.
  • If a java.security.NoSuchAlgorithmException exception is thrown when a SunPKCS11 application is run and the algorithm is one that is supported in the supported algorithms list for z/OS. This behavior might be due to the z/OS hardware cryptographic cards not being available. Contact your system administrator if this issue occurs.
  • Key wrapping is supported through the javax.crypto.Cipher wrap and unwrap methods. Only certain wrapping scenarios are supported on z/OS. They are as follows.
    • Wrapping an RSA private key by using a DES, DESede, or AES key
    • Wrapping a DES, DESede, or AES key by using an RSA public key
    • Wrapping a DES, DESede, or AES key by using a DES, DESede, or AES key is not supported. Also, wrapping an RSA private key with an RSA public key is not supported.
  • When a SunPKCS11 key is set into the PKCS#11 keystore by using the KeyStore.setKeyEntry method, the key object is copied to the TKDS, and the token attribute is set to true. The SunPKCS11 key that is passed into setKeyEntry is no longer valid. A call to the KeyStore.getKey method must be done to retrieve the valid key object from the TKDS.
  • It is recommended that separate tokens be used if your Java PKCS#11 application runs in multiple JVMs or processes and adds and deletes objects in the TKDS. For example, if you run a Java PKCS#11 application that creates a new RSA public and private key pair, then does a KeyStore.load, followed by a Keystore.setKeyEntry for the new RSA private key, followed by a Keystore.deleteEntry of that RSA private key on JVM #1 using TOKEN1. And on JVM #2, the Java PKCS#11 application does a Keystore.load using TOKEN1 before the KeyStore.deleteEntry being done in JVM #1, unpredictable results might occur.
  • When using the tokenlabel attribute in the Java PKCS#11 configuration file, it is recommended that token access (controlled by the SAF CRYPTOZ class resources) be limited to the tokens created for or by each Java PKCS#11 user. For example, user ADMIN would have a SAF CRYTPOZ profile defined for SO.ADMIN* and USER.ADMIN*, and would have CONTROL access to these two CRYPTOZ profiles. Tokens created for or by user ADMIN with the RACF® RACDCERT or System SSL gskkyman tools would have a token name of ADMIN1, for example. Setting up token access using this sort of technique limits the PKCS#11 object visibility. It allows methods like SunPKCS11's KeyStore.engineLoad that loads a keystore with a token's private key, certificate, and secret key objects to complete faster as fewer objects need to be loaded.
  • Tracing for the SunPKCS11 provider can be enabled by setting the parameter -Djava.security.auth.debug=sunpkcs11 while using the java command. Details for enabling tracing for the z/OS PKCS#11 ICSF C-API are described in the z/OS Cryptographic Services ICSF Writing PKCS#11 Applications for your version of z/OS. Refer to PKCS #11: Cryptographic Token Interface Standard, for definitions of which cryptographic algorithms, key objects and key lengths are supported by the SunPKCS11 provider. Also, refer to Oracle PKCS#11 Reference Guide, for more information about the Oracle SunPKCS11 provider.