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