CKM_ECDH1_DERIVE

Supported Operations

Encrypt and Decrypt	No
Sign and Verify	No
SignRecover and VerifyRecover	No
Digest	No
Generate Key/Key-Pair	No
Wrap and Unwrap	No
Derive	Yes
FIPS-approved	Yes

Key Size Range (bytes) and Parameters

Minimum	64
FIPS Minimum	224
Maximum	571
Parameter	`CK_ECDH1_DERIVE_PARAMS`

Description

The elliptic curve Diffie-Hellman (ECDH) key derivation mechanism, denoted CKM_ECDH1_DERIVE, is a mechanism for key derivation based on the Diffie- Hellman version of the elliptic curve key agreement scheme, as defined in ANSI X9.63, where each party contributes one key pair all using the same EC domain parameters.

This mechanism has a parameter, a CK_ECDH1_DERIVE_PARAMS structure.

typedef struct CK_ECDH1_DERIVE_PARAMS {
    CK_EC_KDF_TYPE kdf;/* key derivation function */
    CK_ULONG  ulSharedDataLen;/* optional extra shared data */
    CK_BYTE_PTR pSharedData;
    CK_ULONG   ulPublicDataLen;/* other party public key value */
    CK_BYTE_PTR  pPublicData;
} CK_ECDH1_DERIVE_PARAMS;
typedef struct CK_ECDH1_DERIVE_PARAMS * CK_ECDH1_DERIVE_PARAMS_PTR;

The fields of the structure have the following meanings:

kdf	This is the Key Derive Function (see below for the description of the possible values of this field).
ulSharedDataLen	This is the length of the optional shared data used by some of the key derive functions. This may be zero if there is no shared data.
pSharedData	This is the address of the optional shared data or NULL if there is no shared data.
ulPublicDataLen	This is the length of the other party public key.
pPublicData	This is the pointer to the other party public key. Only uncompressed format is accepted.

The mechanism calculates an agreed value using the EC Private key referenced by the base object handle and the EC Public key passed to the mechanism through the pPublicData field of the mechanism parameter.

The length of the agreed value is equal to the ‘q’ value of the underlying EC curve.

The agreed value is then processed by the Key Derive Function (kdf) to produce the CKA_VALUE of the new Secret Key object.

Four main types of KDFs are supported:

>The NULL KDF performs no additional processing and can be used to obtain the raw agreed value.
Basically: Key = Z

>The CKF_<hash>_KDF algorithms are based on the algorithm described in section 5.6.3 of ANSI X9.63 2001. Basically: Key = H(Z || counter || OtherInfo)

>The CKF_<hash>_SES_KDF algorithms are based on the variant of the x9.63 algorithm specified in Technical Guideline TR-03111 - Elliptic Curve Cryptography (ECC) based on ISO 15946 Version 1.0, Bundesamt Fur Sicherheit in der Informationstechnik (BSI)

Basically: Key = H(Z || counter) where counter is a user specified parameter

>The CKF_<hash>_NIST_KDF algorithms are based on the algorithm described in NIST 800-56A Concatenisation Algorithm

Basically: Key = H(counter || Z || OtherInfo)

The CKF_SES_<hash>_KDF algorithms require the value of the counter to be specified. This is done by arithmetically adding the counter value to the CKF value.

The following Counter values are defined in TR-03111:

Counter Name	Value	Description
`CKD_SES_ENC_CTR`	0x00000001	Default encryption Key
`CKD_SES_AUTH_CTR`	0x00000002	Default authentication Key
`CKD_SES_ALT_ENC_CTR`	0x00000003	Alternate encryption Key
`CKD_SES_ALT_AUTH_CTR`	0x00000004	alternate Authentication Key
`CKD_SES_MAX_CTR`	0x0000FFFF	Maximum counter value

For example:

To derive a session key to be used as an Alternate key for Encryption the counter must equal 0x00000003. If the SHA-1 hash algorithm is required then the kdf value would be set like this:

CK_ECDH1_DERIVE_PARAMS Params;
Params.kdf = CKD_SHA1_SES_KDF + CKD_SES_ALT_ENC_CTR;

The table below describes the supported KDFs.

KDF Type	Description
`CKD_NULL`	The null transformation. The derived key value is produced by taking bytes from the left of the agreed value. The new key size is limited to the size of the agreed value. The Shared Data is not used by this KDF and pSharedData should be NULL.
`CKD_SHA1_KDF`	This KDF generates secret keys of virtually any length using the algorithm described in X9.63 with the SHA-1 hash algorithm. Shared data may be provided.
`CKD_SHA224_KDF`	This KDF generates secret keys of virtually any length using the algorithm described in X9.63 with the SHA-224 hash algorithm. Shared data may be provided.
`CKD_SHA256_KDF`	This KDF generates secret keys of virtually any length using the algorithm described in X9.63 with the SHA-256 hash algorithm. Shared data may be provided.
`CKD_SHA384_KDF`	This KDF generates secret keys of virtually any length using the algorithm described in X9.63 with the SHA-384 hash algorithm. Shared data may be provided.
`CKD_SHA512_KDF`	This KDF generates secret keys of virtually any length using the algorithm described in X9.63 with the SHA-512 hash algorithm. Shared data may be provided.
`CKD_RIPEMD160_KDF`	This KDF generates secret keys of virtually any length using the algorithm described in X9.63 with the RIPE MD 160 hash algorithm. Shared data may be provided. This KDF is not available if the HSM is configured for “Only allow Fips Approved Algorithms”.
`CKD_SHA1_SES_KDF`	This KDF generates session keys. It uses the algorithm described in TR-03111 with the SHA-1 hash algorithm. Shared data may be provided but typically it is not used. The counter value that is a parameter to this KDF must be added to this constant.
`CKD_SHA224_SES_KDF`	This KDF generates single, double and triple length DES keys that are intended for Encryption operations. It uses the algorithm described in TR-03111 with the SHA-224 hash algorithm. Shared data may be provided but typically it is not used. The counter value that is a parameter to this KDF must be added to this constant.
`CKD_SHA256_SES_KDF`	This KDF generates single, double and triple length DES keys that are intended for Encryption operations. It uses the algorithm described in TR-03111 with the SHA-256 hash algorithm. Shared data may be provided but typically it is not used. The counter value that is a parameter to this KDF must be added to this constant.
`CKD_SHA384_SES_KDF`	This KDF generates single, double and triple length DES keys that are intended for Encryption operations. It uses the algorithm described in TR-03111 with the SHA-384 hash algorithm. Shared data may be provided but typically it is not used. The counter value that is a parameter to this KDF must be added to this constant.
`CKD_SHA512_SES_KDF`	This KDF generates single, double and triple length DES keys that are intended for Encryption operations. It uses the algorithm described in TR-03111 with the SHA-512 hash algorithm. Shared data may be provided but typically it is not used. The counter value that is a parameter to this KDF must be added to this constant.
`CKD_RIPEMD160_SES_KDF`	This KDF generates single, double and triple length DES keys that are intended for Encryption operations. It uses the algorithm described in TR-03111 with the Ripe MD 160 hash algorithm. Shared data may be provided but typically it is not used. The counter value that is a parameter to this KDF must be added to this constant. This KDF is not available if the HSM is configured for “Only allow Fips Approved Algorithms”.
`CKD_SHA1_NIST_KDF`	This KDF generates secret keys of virtually any length using the algorithm described in NIST 800-56A with the SHA-1 hash algorithm. Shared data should be formatted according to the standard.
`CKD_SHA224_NIST_KDF`	This KDF generates secret keys of virtually any length using the algorithm described in NIST 800-56A with the SHA-224 hash algorithm. Shared data should be formatted according to the standard.
`CKD_SHA256_NIST_KDF`	This KDF generates secret keys of virtually any length using the algorithm described in NIST 800-56A with the SHA-256 hash algorithm. Shared data should be formatted according to the standard.
`CKD_SHA384_NIST_KDF`	This KDF generates secret keys of virtually any length using the algorithm described in NIST 800-56A with the SHA-384 hash algorithm. Shared data should be formatted according to the standard.
`CKD_SHA512_NIST_KDF`	This KDF generates secret keys of virtually any length using the algorithm described in NIST 800-56A with the SHA-512 hash algorithm. Shared data should be formatted according to the standard.
`CKD_RIPEMD160_NIST_KDF`	This KDF generates secret keys of virtually any length using the algorithm described in NIST 800-56A with the RIPE MD 160 hash algorithm. Shared data should be formatted according to the standard. This KDF is not available if the HSM is configured for “Only allow Fips Approved Algorithms”.

This mechanism derives a secret value, and truncates the result according to the CKA_KEY_TYPE attribute of the template and, if it has one and the key type supports it, the CKA_VALUE_LEN attribute of the template. (The truncation removes bytes from the leading end of the secret value.) The mechanism contributes the result as the CKA_VALUE attribute of the new key; other attributes required by the key type must be specified in the template.

The following rules apply to the provided attribute template:

>A key type must be provided in the template or else a Template Error is returned.

>If no length is provided in the template then that key type must have a well-defined length. If it doesn’t, an error is returned.

>If both a key type and a length are provided in the template, the length must be compatible with that key type.

>If a DES key is derived with these mechanisms, the parity bits of the key are set properly.

>If the requested type of key requires more bytes than the Key Derive Function can provide, an error is generated.

The mechanisms have the following rules about key sensitivity and extractability:

>The CKA_SENSITIVE, CKA_EXTRACTABLE and CKA_EXPORTABLE attributes in the template for the new key can both be specified to be either CK_TRUE or CK_FALSE. If omitted, these attributes all take on the default value TRUE.

>If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key will as well. If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its CKA_SENSITIVE attribute.

>Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then the derived key will, too. If the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_TRUE, then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite value from its CKA_EXTRACTABLE attribute.

Return to SafeNet ProtectToolkit-C Mechanisms