Function Prototype
aat_int32 AAL2GenMigratePKBlobCmd(
aat_byte *Cmd,
aat_int32 *CmdSize,
aat_ascii *PKBlob,
TKernelParms *CallParms,
aat_ascii *aDecryptionKeyNameIn,
aat_ascii *aDecryptionIVIn,
aat_ascii *aEncryptionKeyNameIn,
aat_ascii *aEncryptionIVIn);
Description
This function creates a command which directs the HSM to migrate the payload key BLOB using the given data to return a result in the form of a reply. Migrating the protection keys for a given payload key BLOB does not change the payload key, but only the keys used to protect the BLOB.
This payload key BLOB HSM migration function can be used to:
- Convert a software-encrypted payload key BLOB into an HSM storage key encrypted BLOB (i.e. software-encrypted > HSM-encrypted) ready to be stored in the database. This is not applicable in case of a payload key BLOB directly generated from Authentication Suite Server SDK for HSM.
- Migrate an HSM storage key encrypted payload key BLOB to another HSM storage key-encrypted payload key BLOB (i.e. HSM storage key 1 > HSM storage key 2).
The payload key BLOBHSM protection key migration is only applicable to hardware and software Digipass compliant with the Secure Channel protocol.
This function must be used with the post-HSM API AAL2ProcMigratePKBLOBRpl().
OneSpan recommends using the new function AAL2GenMigratePKBlobCmdEx rather than AAL2GenMigratePKBlobCmd.
Parameters
Table: Parameters (AAL2GenMigratePKBlobCmd) | Type | Name | Use | Description |
|---|
| aat_byte * | Cmd | O | Up to 450 bytes that serialize the MIGRATE PAYLOAD KEY BLOB command type and the input data to the migrate payload key BLOB function in the HSM: - Command type - 2 bytes
- PayloadKey BLOB - 72 characters
- Runtime parameters - 80 bytes
- DecryptionKeyName - up to 128 characters
- DecryptionInitialVector - up to 8 bytes
- EncryptionKeyName - up to 128 characters
- EncryptionInitialVector - up to 8 bytes
Plus 24 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. |
| aat_ascii * | PKBlob | I | String of 88+1 characters, null-terminated. Contains the payload key BLOB to migrate. |
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 perform the decryption of the HSM encrypted payload key BLOB. This is the label of the HSM storage key used to decrypt the payload key BLOB in input for migration from the HSM storage key-encrypted payload key BLOB to another HSM storage key. Must be NULL or empty if the payload key 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. |
| aat_ascii * | aEncryptionKeyNameIn | I | String containing the HSM encryption key label used to perform the 3DES/AES encryption of the sensitive data of the payload key BLOB. This is the label of the HSM storage key used to encrypt the sensitive payload key BLOB data in output. After migration, further usage of the payload key 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 payload key BLOB data in output. Can be NULL to encrypt the payload key BLOB without any initial vector. After migration, further usage of the payload key BLOB will mandatorily require to use this initial vector. |
Return codes
Table: Return codes (AAL2GenMigratePKBlobCmd) | Code | Meaning | Code | Meaning |
|---|
| 0 | Success | 1018 | Invalid TLV item pointer |
| 149 | Invalid initial vector length | 1100 | Function not supported |
| 412 | Invalid checksum (software) | 1119 | Unsupported payload key BLOB |
| 413 | Invalid Base64 format | 1025 | Data buffer too small |
| 590 | Invalid command pointer | 1286 | Invalid payload key pointer |
| 706 | Invalid data buffer pointer | | |