Function prototype
aat_int32 AAL2GenMigrateBlobCmdEx(
aat_byte *Cmd,
aat_int32 *CmdSize,
TDigipassBlob *DPData,
TKernelParms *CallParms,
aat_ascii *aDecryptionKeyNameIn,
aat_ascii *aDecryptionIVIn,
aat_ascii *aTransportKeyKCVIn,
aat_ascii *aEncryptionKeyNameIn,
aat_ascii *aEncryptionIVIn);
Description
This function extends AAL2GenMigrateBlobCmd by allowing you to specify key names and initial vectors in parameters. In addition, this function allows you to migrate an HSM DPX transport key encrypted BLOB into an HSM storage key encrypted BLOB.
This authenticator application BLOB migration function can be used to:
- Convert a software-encrypted BLOB into an HSM storage key encrypted BLOB (i.e. software-encrypted > HSM-encrypted) ready to be stored in the database.
- Migrate an HSM-level DPX transport key encrypted BLOB (after import from a double encrypted DPX file) into an HSM storage key encrypted BLOB (i.e. HSM-level DPX transport key > HSM storage key) ready to be stored in the database.
- Migrate an HSM storage key encrypted BLOB to another HSM storage key encrypted BLOB (i.e. HSM storage key 1 > HSM storage key 2).
- Migrate software protection keys for a given authenticator application BLOB. When a new value is set for StorageDeriveKey(1-4) in the kernel parameters that are passed to AAL2GenMigrateBlobCmd, the software key that additionally protects the authenticator application BLOBs is also changed (along with the HSM key rotation).
If aDecryptionKeyNameIn and aEncryptionKeyNameIn are filled, these parameters override the CallParms > TransportKeyId and CallParms > StorageKeyId parameters. In this case, the keys are passed with their names.
You can acquire a software encrypted BLOB or HSM-level DPX transport key encrypted BLOB using the Digipass Data Import Service of Authentication Suite Server SDK for HSM. This will extract a BLOB but not migrate it. For more information on this service, refer to the Authentication Suite Server SDK for HSM Product Guide.
An HSM-level DPX transport key encrypted BLOB can only be acquired if the relevant DPX file has been created using HSM-level DPX transport key encryption (double encrypted DPX file).
This function must be used with the post-HSM API AAL2ProcMigrateBlobRpl().
Parameters
Table: Parameters (AAL2GenMigrateBlobCmdEx) | Type | Name | Use | Description |
|---|
| aat_byte * | Cmd | O | Up to 580 bytes that serialize the MIGRATE BLOB command type and the input data to the migrate BLOB function in the HSM: - Command type - 2 bytes
- An authenticator application BLOB - 192 bytes
- Runtime parameters - 80 bytes
- DecryptionKeyName - up to 128 characters
- DecryptionInitialVector - up to 8 bytes
- TransportKeyKCV - 6 bytes
- EncryptionKeyName - up to 128 characters
- EncryptionInitialVector - up to 8 bytes
Plus 28 bytes for Authentication Suite Server SDK internal use. |
| aat_int32 * | CmdSize | I/O | On entry, this parameter contains the size of the Cmd buffer.On exit, this parameter contains the length of the Cmd message. |
| TDigipassBlob * | DPData | I | authenticator application BLOB. |
| TKernelParms * | CallParms | I | Structure of runtime parameters to use during this function call. |
| aat_ascii * | aDecryptionKeyNameIn | I | String containing the HSM key label used to decrypt the sensitive data of an HSM encrypted BLOB. This can be either of the following: - the label of the HSM transport key used to decrypt the HSM-level DPX transport key encrypted BLOB in input after import from a double encrypted DPX file.
- the label of the HSM storage key used to decrypt the BLOB in input in case of migration from HSM storage key encrypted BLOB to another HSM storage key.
Must be NULL or empty if the BLOB in input is software-encrypted. |
| aat_ascii * | aDecryptionIVIn | I | String containing the decryption initial vector of the HSM-encrypted payload key BLOB in input. Must be NULL if the payload key BLOB in input is software-encrypted, or if the payload key BLOB in input is HSM-level DPX transport key- encrypted (after import from a double encrypted DPX file). |
| aat_ascii * | aTransportKeyKCVIn | I | String containing the KCV of the DPX transport key. Must be NULL or empty if the payload key BLOB in input is software-encrypted, or if the payload key BLOB in input is HSM storage key-encrypted. |
| aat_ascii * | aEncryptionKeyNameIn | I | String containing the HSM encryption key label used to perform the 3DES/AES encryption of the sensitive data of the BLOB. This is the label of the HSM storage key used to encrypt the sensitive authenticator application BLOB data in output. After migration, further usage of the authenticator application BLOB will mandatorily require to use this HSM storage key. |
| aat_ascii * | aEncryptionIVIn | I | String of 16 hexadecimal digits containing the initial vector. This is the initial vector used to encrypt the sensitive authenticator application BLOB data in output. Can be NULL to encrypt the BLOB without any initial vector. After migration, further usage of the authenticator application BLOB will mandatorily require to use this initial vector. |
Return codes
Table: Return codes (AAL2GenMigrateBlobCmdEx) | Code | Meaning | Code | Meaning |
|---|
| 0 | Success | 590 | Invalid command pointer |
| 149 | Invalid initial vector length | 706 | Invalid data buffer pointer |
| 151 | Invalid KCV length | 1000 | Function does not support EMV-CAP |
| 412 | Invalid checksum (software) | 1018 | Invalid TLV item pointer |
| 413 | Invalid Base64 format | 1025 | Data buffer too small |
| 510 | Invalid Digipass data pointer | | |