Using ECDH to derive AES keys

As a prerequisite to use the CKM_ECDH1_DERIVE mechanism during the derivation with C_DeriveKey(), the base key must be an ECC key which, for the CCA token, is generated already together with the information, which key types and lengths will be allowed to be derived from this key. CCA stores this information in the ECC key (base key) itself. As default, the CCA token key generation functions produce keys that you can use to derive AES 256 keys. For further derivation requirements, you must customize the ECC key generation process. See also table ECC key-derivation information section (X'23') in the Secure Key Solution with the Common Cryptographic Architecture Application Programmer's Guide.

For the ECC base key, to supply this early information about the future to-be-derived keys at generation time, the user can supply attribute CKA_DERIVE_TEMPLATE in the private key template used for ECC key generation.

Attribute CKA_DERIVE_TEMPLATE is an array-attribute, that itself contains a list of attributes (that is, a template). This derive template is then supplied to the to-be-derived key during key derivation. Attribute CKA_DERIVE_TEMPLATE can be supplied during key creation only (generate, import, unwrap, derive), but can not be modified afterward. Refer to the PKCS #11 Specification Version 3.1 for more details about the CKA_DERIVE_TEMPLATE attribute.

The attributes that are contained in CKA_DERIVE_TEMPLATE and that are relevant for the ECC key derivation are the following:

CKA_KEY_TYPE

specifies the key type of the to-be-derived key. If contained in CKA_DERIVE_TEMPLATE, it must be CKK_AES. Even if not contained, then the key type used for the ECC key derivation is AES.

CKA_VALUE_LEN

specifies the size of the AES key in bytes. Supported values for AES keys are 16 (128 bits), 24 (192 bits), and 32 (256 bits). If contained in CKA_DERIVE_TEMPLATE, the desired key size is used for the ECC key derivation info section (X’23’). Otherwise the key size in the ECC key derivation info section (X’23’) is set to 256 bits (that is, an AES-256 bit key is derived by default).

CKA_IBM_CCA_AES_KEY_MODE

specifies the CCA AES key mode. Can be either CK_IBM_CCA_AES_DATA_KEY (0) to derive a CCA AES DATA key or CK_IBM_CCA_AES_CIPHER_KEY (1) to derive a CCA AES CIPHER key.

If contained in the CKA_DERIVE_TEMPLATE, the desired key mode is used to already define the resulting mode of the derived keys (when using C_DeriveKey() with the CKM_ECDH1_DERIVE mechanism). Otherwise the key mode of the derived key is set to the token-global default as specified with setting AES_KEY_MODE in the CCA token configuration file.

If no AES_KEY_MODE setting is specified, or no CCA token configuration file exists, then the key mode is set to derive AES DATA keys.

Attribute CKA_DERIVE_TEMPLATE can contain additional attributes to be supplied to the to-be-derived key, but those are not relevant when used with ECC key derivation.

If no CKA_DERIVE_TEMPLATE attribute is specified during ECC key generation, then such ECC key can derive AES-256 bit keys only. In such a case, the derived key mode is dependent on the current setting of the AES key mode for the CCA token (retrieved from 1. the setting in the CCA token configuration file, or 2. using the default CCA AES DATA).

Setting the required ACPs

If you want to perform key derivation using ECDH with a specific curve, you must have set the corresponding access control point.

Restrictions with using ECDH for derivation

There are some use cases with restrictions on the base ECC key, that you must observe if you want to use the ECC key for derivation with ECDH.

• The most general restriction is that the attempt to derive keys that do not match the information contained in the ECC key derivation info section X’23’ (that is, the information that has been applied to the private ECC key (base key) with the CKA_DERIVE_TEMPLATE attribute), will fail with CKR_ATTRIBUTE_VALUE_INVALID.
• Key derivation using existing ECC private keys, that have been generated with a CCA token version prior to openCryptoki 3.24, does not allow to perform ECDH (even though these keys might have CKA_DERIVE=TRUE).
• CCA allows derivation with ECDH only from randomly generated ECC keys. This has consequences on importing keys with a PKCS #11 application. As CCA flags all keys imported from clear key values as not being randomly generated, the PKCS #11 application must apply the attribute CKA_DERIVE set to FALSE during the import to keep the conditions of PKCS #11 and CCA consistent. Trying to import an EC private key from a clear key with CKA_DERIVE set to TRUE will fail with CKR_TEMPLATE_INCONSISTENT. Note that the default setting for CKA_DERIVE is FALSE.

  To sum up: PKCS #11 key objects that you want to use by the CCA token for key derivation, must have been generated by random using the C_GenerateKeyPair() function and must have attribute CKA_DERIVE = TRUE. Keys imported from clear can not be used for key derivation and thus can not have CKA_DERIVE = TRUE.

• When importing an existing CCA ECC secure key token (key blob) containing an ECC private key, and CKA_DERIVE is set to TRUE, then the CCA token checks that the ECC secure key token has been generated by random. If this is not the case, CKR_ATTRIBUTE_VALUE_INVALID is returned.

  Furthermore, if the key token key blob contains an ECC key derivation info section (X’23’), it is checked that its contents (key type, key size, key mode) is supported by the CCA token. This means, it must allow to derive AES keys only, with a proper key size (128, 192, 256 bits), and either specify a CCA DATA or CIPHER key type. If the key derivation info section contains unsupported values, then CKR_ATTRIBUTE_VALUE_INVALID is returned.