AAL2MigratePKBlobICSFEx

Mis à jour le 22 Jan 2025
3 Minutes à lire

Partager
Sombre
Lumière
PDF

The content is currently unavailable in French. You are viewing the default English version.

Résumé de l’article

Avez-vous trouvé ce résumé utile ?

Merci pour vos commentaires

Function prototype

aat_int32 AAL2MigratePKBlobICSFEx (
                             aat_ascii*      PKBlob,
                             TKernelParms*   CallParms,
                             aat_ascii*      aOldStorageKeyName,
                             aat_ascii*      aOldInitialVector,
                             aat_ascii*      aNewStorageKeyName,
                             aat_ascii*      aNewInitialVector,
                             aat_ascii*      aTransportKeyKCV);

Description

This function is used to migrate HSM protection keys for a given payload key BLOB. 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.

It is only applicable to hardware or software Digipass compliant with the secure channel protocol; for more information, refer to the OneSpan Authentication Suite Server SDK Product Guide).

The BLOB migration function can be used to:

Convert a payload key BLOB encrypted with a software storage key to a payload key BLOB encrypted with an HSM storage key
(i.e. software → HSM-encrypted) payload key BLOB 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 ICSF.
Migrate an HSM storage key encrypted payload key BLOB to a new HSM storage key encrypted payload key BLOB
(i.e. HSM storage key 1 → HSM storage key 2).
Migrate an HSM transport key encrypted payload key BLOB to an storage key encrypted payload key BLOB
(i.e. HSM transport key → HSM storage key).

Parameters

Table: Parameters (AAL2MigratePKBlobICSFEx)
Type	Name	Use	Description
aat_ascii *	PKBlob	I/O	88+1 characters string, null-terminated. Contains the payload key BLOB to migrate from existing software protection keys to new ones.Upon return from the function call, this BLOB must be rewritten to the application database to reflect changes.
TKernelParms *	CallParms	I	Structure of runtime parameters to use during this function call. (Contains the old values of the derive vector and storage derive keys that may have been used initially to software encrypt the PKBLOB.)
aat_ascii *	aOldStorageKeyName	I	String containing the HSM key label used to perform the decryption of the sensitive data of the payload key BLOB in input. This can be one of the following: the label of the HSM storage key used to decrypt the payload key BLOB in case of storage key migration. the label of the HSM transport key used to decrypt the payload key BLOB in case of DPX transport key migration (after import from a double encrypted DPX file). This parameter has to be set to blank (NULL) when migrating a software encrypted payload key BLOB.
aat_ascii *	aOldInitialVector	I	String containing the decryption initial vector to be used during the decryption of the payload key BLOB in input. This parameter has to be set to blank when migrating a software encrypted payload key BLOB or when migrating from an HSM transport key (after import from a double encrypted DPX file).
aat_ascii *	aNewStorageKeyName	I	String containing the HSM storage key used to perform the 3DES/AES encryption of the sensitive data of the payload key BLOB in output. After migration, further usage of the payload key BLOB will mandatorily require to use this HSM storage key.
aat_ascii *	aNewInitialVector	I	16 hexadecimal containing the initial vector. This is the initial vector used to perform the encryption of the sensitive data of the payload key BLOB 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.
aat_ascii*	aTransportKeyKCV	I	String containing the KCV of the HSM transport key used to perform the DPX decryption of the sensitive data of the payload key BLOB (after import from a double encrypted DPX file). This parameter has to be set to blank (NULL) when migrating a software encrypted payload key BLOB or when migrating from an HSM storage key.

COBOL calling convention

Entry point: AA2MPBIE
02   W-PKBLOB               PIC X(89).
02   W-KERNELPARMS.
     03  W-PARMCOUNT        PIC 9(8) USAGE BINARY.
     03  W-PARM01           PIC 9(8) USAGE BINARY.
     . . .
     03  W-PARM19           PIC 9(8) USAGE BINARY.
02   W-RETURN               PIC S9(8) USAGE BINARY.
02   W-OLDSTORAGEKEY        PIC X(65).
02   W-OLDINITVECTOR        PIC X(17).
02   W-NEWSTORAGEKEY        PIC X(65).
02   W-NEWINITVECTOR        PIC X(17).
02   W-TRANSPORTKEYKCV      PIC X(7).
02   W-API-NAME             PIC X(8) VALUE 'AA2MPBIE'.
. . .
     CALL W-API-NAME USING
           BY REFERENCE W-PKBLOB
           BY REFERENCE W-KERNELPARMS
           BY REFERENCE W-OLDSTORAGEKEY
           BY REFERENCE W-OLDINITVECTOR
           BY REFERENCE W-NEWSTORAGEKEY
           BY REFERENCE W-NEWINITVECTOR
           BY REFERENCE W-TRANSPORTKEYKCV
           RETURNING W-RETURN

Return codes

Table: Return codes (AAL2MigratePKBlobICSFEx)
Code	Meaning	Code	Meaning
0	Success	951	Invalid HSM key type for HSM decryption
412	Invalid checksum (software)	1100	Function not supported
413	Invalid Base64 format	1119	Unsupported payload key BLOB
414	Invalid checksum (HSM)	1286	Invalid payload key pointer
900	Invalid session context handle	-1501	Memory allocation failed
908	HSM key not found

Cet article vous a-t-il été utile ?

What's Next

AAL2ProcMessageInformationICSF

Table des matières

Function prototype
Description
Parameters
COBOL calling convention
Return codes