Usage notes for the EP11 host library functions

Edit online

In this topic, you find information about certain limitations of the EP11 host library.

  • The EP11 host library implements the secure key concept as explained in the introduction of CCA token.

    Therefore, the EP11 token only knows sensitive secret keys (CKO_SECRET_KEY). However, the PKCS #11 standard defines the default value of attribute CKA_SENSITIVE to be CK_FALSE. Thus, for previous versions of the EP11 token, all applications must have the attribute value of CKA_SENSITIVE explicitly changed to CK_TRUE whenever an EP11 secret key had been generated, unwrapped, or build with C_CreateObject.

    Starting with the EP11 token for openCryptoki version 3.10, an option is implemented to change the default value of attribute CKA_SENSITIVE to be CK_TRUE for all secret keys created with the EP11 token. This applies to functions C_GenerateKey, C_GenerateKeyPair, C_UnwrapKey, and C_DeriveKey when creating key with CKA_CLASS = CKO_SECRET_KEY, if the attribute CKA_SENSITIVE is not explicitly specified in the template.

    To enable this option, you must specify keyword FORCE_SENSITIVE in the EP11 token configuration file, as shown in Figure 1. Note that the semantics specified with the FORCE_SENSITIVE keyword matches the semantics used by z/OS® for EP11.

    Figure 1. Sample of an EP11 token configuration file
    #
# EP11 token configuration
#
FORCE_SENSITIVE
#
APQN_ALLOWLIST
  5 2
  6 2
END
  • Keys leaving the hardware security module (HSM) are encrypted by the HSM master key (wrapping key) and come as binary large object (BLOB). In openCryptoki, objects can have special attributes that describe the key properties. Besides dedicated attributes defined by the application, there are some attributes defined as token-specific by openCryptoki.

    Table 1 and Table 2 show the EP11 token-specific attributes and their default values for private and secure keys.

    Table 1. Private key (CKO_PRIVATE_KEY) default attributes of the EP11 token
    Private key attributes value
    CKA_SENSITIVE CK_TRUE
    CKA_EXTRACTABLE CK_TRUE
    Table 2. Secret key (CKO_SECRET_KEY) default attributes of the EP11 token
    Secret key attributes value
    CKA_EXTRACTABLE CK_TRUE
  • When you create keys the default values of the attributes CKA_ENCRYPT, CKA DECRYPT, CKA_VERIFY, CKA_SIGN, CKA_WRAP and CKA_UNWRAP are CK_TRUE. Note, no EP11 mechanism supports the Sign/Recover or Verify/Recover functions.

    Even if settings of CKA_SENSITIVE, CKA_EXTRACTABLE, or CKA_NEVER_EXTRACTABLE would allow accessing the key value, then openCryptoki returns 00..00 as key value (due to the secure key concept).

    For information about the key attributes, see the PKCS #11 Cryptographic Token Interface Standard.

  • All RSA keys must have a public exponent (CKA_PUBLIC_EXPONENT) greater than or equal to 17.
  • The Crypto Express EP11 coprocessor restricts RSA keys (primes and moduli) according to ANSI X9.31. Therefore, in the EP11 token, the lengths of the RSA primes (p or q) must be a multiple of 128 bits. Also, the length of the modulus (CKA_MODULUS_BITS) must be a multiple of 256.
  • The mechanisms CKM_DES3_CBC and CKM_AES_CBC can only wrap keys, which have a length that is a multiple of the block size of DES3 or AES respectively. See the mechanism list and mechanism information (pkcsconf -m) for supported mechanisms together with supported functions and key sizes.
  • The EP11 coprocessor adapter can be configured to restrict the cryptographic capabilities in order for the adapter to comply with specific security requirements and regulations. Such restrictions on the adapter impact the capability of the EP11 token.
  • The PKCS #11 function C_DigestKey() is not supported by the EP11 host library.
  • Pure EP11 key objects can be extracted from sensitive openCryptoki key objects for the CCA token by accessing the value of the CKA_IBM_OPAQUE attribute value.