Usage notes for the EP11 host library functions

Edit online

In this topic, on the one hand, you find information about certain limitations of the EP11 host library, but you also find information on how to exploit certain features of that 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.

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

Importing and exporting EP11 secure key blobs

The EP11 token supports exporting and importing EP11 secure key blobs. Both functions use the CKA_IBM_OPAQUE attribute: importing sets the key blob in this attribute and exporting retrieves the key blob from this attribute.

To export an EP11 secure key blob from a PKCS #11 key object of the EP11 token, use function C_GetAttributeValues() to retrieve the CKA_IBM_OPAQUE attribute.

To import an EP11 secure key blob into a PKCS #11 key object of the EP11 token, use function C_CreateObject() and specify attribute CKA_IBM_OPAQUE together with the CKA_CLASS and CKA_KEY_TYPE attributes. Besides those, additional attributes like the boolean attributes can optionally also be specified. C_CreateObject() then extracts all non-sensitive key components and attributes from the EP11 secure key blob and supplies them in appropriate attributes to the newly created key object.

Any boolean attributes specified by the user with C_CreateObject() must be compatible with those attributes that are available in the EP11 secure key object. Otherwise CKR_ATTRIBUTE_VALUE_INVALID is returned. Compatible means: Some key usage attributes may be set to TRUE or FALSE during the import of a secure key blob (for example, CKA_SIGN or CKA_ENCRYPT), but only if attribute CKA_MODIFIABLE is TRUE in the key blob. Others can only be set to FALSE during the import of a secure key blob (for example, CKA_EXTRACTABLE or CKA_MODIFIABLE) to further restrict a key. Lifting such a restriction is not possible. If boolean attributes are changed during import, then the EP11 secure key blob is updated to reflect these changes.

openCryptoki also checks that the key blob to be imported uses the right master key (wrapping key). That is, it must use the same master key as used by the EP11 token. Otherwise CKR_ATTRIBUTE_VALUE_INVALID is returned.

openCryptoki further checks if the key blob to be imported is session bound or not. Dependent on the mode that the EP11 token currently uses (either strict session mode, virtual HSM mode, or the FIPS session mode), key objects may have to be bound to a certain session. The imported key blob must be bound to the expected session, or no session respectively, as required by the used mode and key attributes. Otherwise CKR_ATTRIBUTE_VALUE_INVALID is returned.

You can import EP11 secure key blobs of secret (symmetric) keys, private keys, and public keys. Importing EP11 secure key blobs require a certain firmware fix. If this fix is not available, then the import might fail with CKR_PUBLIC_KEY_INVALID.