ECIES Enhancement for HKDF
A new KDF definition is added with Luna HSM Firmware 7.8.7, complying with RFC 5869, to expand the utility of the prior ECIES implementation.
The implementation avoids conflict with existing Luna headers:
#define CKD_HKDF_SHA256 0x80000020
/** Mechanism parameter structure for ECIES */
typedef struct CK_ECIES_PARAMS
{
/** Diffie-Hellman primitive used to derive the shared secret value */
CK_EC_DH_PRIMITIVE dhPrimitive; // CKDHP_STANDARD (private key and ephemeral public as input
/** key derivation function used on the shared secret value */
CK_EC_KDF_TYPE kdf; // CKD_HKDF_SHA256
/** the length in bytes of the key derivation shared data */
CK_ULONG ulSharedDataLen1; // sizeof HKDF Shared Data 1
/** the key derivation padding data shared between the two parties */
CK_BYTE_PTR pSharedData1; //HKDF optional
/** the encryption scheme used to transform the input data */
CK_EC_ENC_SCHEME encScheme; // CKES_AES_CTR
/** the bit length of the key to use for the encryption scheme */
CK_ULONG ulEncKeyLenInBits; // 256
/** the MAC scheme used for MAC generation or validation */
CK_EC_MAC_SCHEME macScheme; // CKMS_HMAC_SHA256
/** the bit length of the key to use for the MAC scheme */
CK_ULONG ulMacKeyLenInBits; // 256
/** the bit length of the MAC scheme output */
CK_ULONG ulMacLenInBits; // 256
/** the length in bytes of the MAC shared data */
CK_ULONG ulSharedDataLen2; // 0
/** the MAC padding data shared between the two parties */
CK_BYTE_PTR pSharedData2; // NULL
} CK_ECIES_PARAMS;
Luna Proprietary Extension to CKM_ECIES
typedef struct CK_ECIES_PARAMS_EXT2
{
/** Legacy ECIES parameters*/
CK_ECIES_PARAMS eciesParams; // as above
/** reference encryption scheme structure extension = AES_CTR params */
CK_VOID_PTR pEncSchemeMechanismParameter; // NULL for zero
/** length encryption scheme structure extension*/
CK_ULONG ulEncSchemeMechanismParameterLen;
/** Flags for ECIES KDF/ENC/DEC additional shared data (sharedData1) * LSB: 0x0000XXXX UInt16 KDF encoding
* 0 = no addition to shared data
* 1 = shared data | ephemeral public key
* 2 = shared data | compressed ephemeral public key
* 3 = ephemeral public key | shared data
* 4 = compressed ephemeral public key | shared data
* MSB: 0xXXXX0000 32 bits Encoding
* 0x0001XXXX NULL ICV for AES_CTR ENC/DEC
* 0x0002XXXX Prepend ephemeral key for KDF */
CK_ULONG ulKDFSharedDataFlags; // Must be 0x00030000 for Google Pay
} CK_ECIES_PARAMS_EXT2;
typedef struct CK_ECIES_PARAMS_EXT3
{
/** Legacy proprietary ECIES_EXT2 parameters*/
CK_ECIES_PARAMS_EXT2 eciesParams; // as above
/** reference derivation scheme structure extension = Salt params */
CK_VOID_PTR pSalt; // NULL for zero
/** length derivation scheme structure extension*/
CK_ULONG ulSaltLen;
} CK_ECIES_PARAMS_EXT3
RULES FOR CK_ECIES_PARAMS_EXT3 USE WITH HKDF
The ulKDFSharedDataFlags field is a proprietary extension, it controls the behavior of the KDF stage. For certain payment use cases it is possible to define flags to selectively enable prepending the ephemeral key to the shared secret to allow using an IV set to 0 for AES_CTR encryption and to control the encoding of the Salt value which could be zero for some use cases.
The pEncSchemeMechanismParameter and ulEncSchemeMechanismParameterLen parameters are used in the symmetric encrypt/Decrypt stage defined by encScheme. This not related to the KDF operation (it comes after). So, adding HKDF support does not affect how pEncSchemeMechanismParameter, ulEncSchemeMechanismParameterLen and encScheme interact.
In the case where encScheme is CKES_AES_CTR, the pEncSchemeMechanismParameter is a pointer to an optional IV value for the AES CTR mode.
The IV pointed at by pEncSchemeMechanismParameter is unrestricted. It should be assumed to mean all zero IV if it is NULL; otherwise, it is handled by AES CTR enc/dec operation as previously implemented.
CK_ECIES_PARAMS_EXT AND CK_ECIES_PARAMS
The CK_ECIES_PARAMS_EXT structure is an older version of the CK_ECIES_PARAMS_EXT2. It lacks the ulKDFSharedDataFlags field.
The CK_ECIES_PARAMS struct is the parameter from PKCS#11. It lacks the pEncSchemeMechanismParameter, ulEncSchemeMechanismParameterLen and ulKDFSharedDataFlags fields.
The latest host library (in client UC 10.7.1 onward) accepts CK_ECIES_PARAMS CK_ECIES_PARAMS_EXT and CK_ECIES_PARAMS_EXT2 convert the information into CK_ECIES_PARAMS_EXT3 by setting the undefined fields to zero/NULL.
Some payment scenarios might require the use of CK_ECIES_PARAMS_EXT2 extended fields.
So, the caller may use either CK_ECIES_PARAMS_EXT2 or CK_ECIES_PARAMS_EXT3 when doing some payment-related decrypts/encrypts.
However older Library implementations (preceding the HKDF feature; earlier than UC 10.7.1) will not work because the library would not recognize the HKDF kdf type (even if the firmware has that feature). Also, only firmware at version 7.8.7 onward can recognize the HKDF type either, so you will need both firmware 7.8.7 onward and client UC 10.7.1 onward, with the newer library, to perform some payment operations (depending on the requirements of your scheme).
DECRYPTION
C_DECRYPTINIT
C_DecryptInit function have the following parameters.
CK_SESSION_HANDLE hSession, The session handle
CK_MECHANISM_PTR pMechanism, A pointer to the ECIES_PARAM_EXT2 structure
CK_OBJECT_HANDLE hKey , The ECC Private key handle
C_DECRYPT
C_Decrypt function have the following parameters.
CK_SESSION_HANDLE hSession, The session handle
CK_BYTE_PTR pEncryptedData, Ephemeral Public Key | Encrypted Data | Signature
CK_ULONG ulEncryptedDataLen, The length of the encryptedData
CK_BYTE_PTR pData, The decrypted message
CK_ULONG_PTR pulDataLen The decrypted message length
ENCRYPTION
The encryption mechanism generates the ephemeral key pair based on the provided ECC public key and associated curve. At the end of the operation the ephemeral public key is returned along with the encrypted data and the ephemeral private key is deleted.
C_ENCRYPTINIT
C_EncryptInit function have the following parameters.
CK_SESSION_HANDLE hSession, The session handle
CK_MECHANISM_PTR pMechanism, A pointer to the ECIES_PARAM_EXT2 structure
CK_OBJECT_HANDLE hKey , The ECC Public key handle
C_ENCRYPT
This process generates an ephemeral ECDSA key pair based on the given Curve OID. Then encryption and mac key are computed and used to encrypt and sign the message.
CK_SESSION_HANDLE HSESSION, THE SESSION HANDLE
CK_BYTE_PTR pData, Data
CK_ULONG uldDataLen, The length of the data
CK_BYTE_PTR pEncData, The ephemeral public key | the encrypted message | MAC
CK_ULONG_PTR pulEncDataLen The encrypted message length
TOOLS
CKDEMO
CKD_HKDF_SHA256 is supported for key derivation of ECIES encryption/decryption mechanism.
Sample Payments Use case:
(98) Options: Turn on option 12- ECIES Parameters.
- Create an ECC key pair
(45) Sample generate key
1. [15] ECDSA
2. [19] X9_62_prime256v1(P-256)+
3. Set up template Sensitive Private Encrypt/Decrypt set to 1.
(40) Encrypt File
1. [51] ECIES and file to encrypt.
2. ECDH Primitive [] ECDH1 with COFACTOR (Standard)
3. KDF Type [35] CKD_HKDF_SHA256_KDF
4. Enter shared data file containing “Google” in ascii.
5. Add Shared data for HKDF [1] prepend ephemeral public key: 1
6. Enter salt data (enter “none” for no data): none
7. Encryption/decryption scheme: [6] = CKES_AES_CTR
a. Enter Number of counter bits for AES CTR mode : 0
b. AES_CTR_IV Derived?
[0] Not Derived
8. Select the AES key size in bits options [3] = 256-bits
9. Available signature/verification schema [5] CKMS_HMAC_SHA256
a. Enter Mac key length in bits (0…1024) 256.
b. Enter Mac length in bits (0…1024) 256
10. Enter shared data file for the HMAC (enter “none” for no data): none
11. Enter key to use. You should use your public key to send message encrypted: The generated ECDSA public key handle.
The encrypted data have been stored in file ENCRYPT.BIN.
The ENCRYPT.BIN file can be decrypted in the same way using the option (41) Decrypt file using your generated private key.
MULTITOKEN AND FMULTITOKEN
These ECIES Encryption Decryption mechanisms have been added to MultiToken and fmultiToken at client version UC 10.7.1 onward.
Command line – multitoken or fmultitoken
-s 1 -mode eciesaes256hkdfsha256hmacsha256 -curve 19 -esch = 1 -psw password -f -t 20
or/and
-s 1 -mode eciesaes256hkdfsha256hmacsha256 -curve 19 -esch = 0 -psw password -f -t 20
