Deactivation message generation

This article describes the function(s) on which the deactivation message generation functionality is based. It contains information about parameters and possible return codes, as well as a prototype for each function.

The deactivation message generation functionality is only applicable to hardware or software Digipass authenticators compliant with the multi-device two-step activation (in the context of multi-device licensing). For more information, refer to the Authentication Suite Server SDK Product Guide.
In addition, the deactivation message generation is only applicable if the Secure Channel feature has been ordered (configured by OneSpan at the time of order).

AAL2GenMessageDeactivationICSF

Function prototype

aat_int32 AAL2GenMessageDeactivationICSF (
                                aat_ascii       *PKBlob,
                                TKernelParms    *CallParms,
                                aat_ascii       *aStorageKeyNameIn,
                                aat_ascii       *aInitialVectorIn,
                                aat_ascii       *MessageVector,
                                aat_int32       SeqNum,
                                aat_ascii       *DeactivationMessage,
                                aat_int32       *DeactivationMessageLength);

Description

This function generates a deactivation message from a sequence number, using the payload key embedded into the payload key BLOB.

It is only applicable to hardware or software Digipass authenticators compliant with the multi-device two-step activation (in the context of multi-device licensing). For more information, refer to the Authentication Suite Server SDK Product Guide.

The payload key BLOB must be the one corresponding to the Digipass serial number the deactivation message will target.

The deactivation message generation is only applicable if the Secure Channel feature has been ordered (configured by OneSpan at the time of order).

Parameters

Table: Parameters (AAL2GenMessageDeactivationICSF)
Type	Name	Use	Description
aat_ascii *	PKBlob	I	Contains the payload key BLOB that has been generated for the Digipass instances activated with a particular serial number license.
TKernelParms *	CallParms	I	Structure of runtime parameters to use during this function call.
aat_ascii *	aStorageKeyNameIn	I	String of up to 64+1 characters, left-justified, null-terminated, or right-padded with spaces. This is the label of the ICSF storage key used to encrypt the sensitive Digipass application BLOB data.
aat_ascii *	aInitialVectorIn	I	String of 16 or 32 hexadecimal characters, left-justified, null-terminated. This is the initial vector used to encrypt the sensitive authenticator application BLOB data.
aat_ascii *	MessageVector	I	A string of up to 26+1 characters containing the message parameter settings, null-terminated (obtained during import).
aat_int32	SeqNum	I	Integer containing the sequence number of the Digipass instance to deactivate.
aat_ascii *	DeactivationMessage	O	String of up to 50+1 hexadecimal characters, null-terminated. In case of a successful operation, this parameter contains the generated deactivation message.
aat_int32 *	DeactivationMessageLength	I/O	In input, this parameter must indicate the size of the allocated buffer for the DeactivationMessage parameter (recommended 51 bytes). In output, this parameter indicates the length of the DeactivationMessage string (without the null-terminated character).

COBOL calling convention

Entry point: AA2GMDIC
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-MSGVECTOR          PIC X(27).
02   W-SEQNUM             PIC 9(8) USAGE BINARY.
02   W-DEACTMSG           PIC X(51).
02   W-DEACTMSG-LENGTH    PIC 9(8) USAGE BINARY VALUE 51.
02   W-RETURN             PIC S9(8) USAGE BINARY.
02   W-STORAGEKEY         PIC X(65).
02   W-INITVECTOR         PIC X(17).
02   W-API-NAME           PIC X(8) VALUE 'AA2GMDIC'.
. . .
     CALL W-API-NAME USING
           BY REFERENCE W-PKBLOB
           BY REFERENCE W-KERNELPARMS
           BY REFERENCE W-STORAGEKEY
           BY REFERENCE W-INITVECTOR
           BY REFERENCE W-MSGVECTOR
           BY REFERENCE W-SEQNUM
           BY REFERENCE W-DEACTMSG
           BY REFERENCE W-DEACTMSG-LENGTH
           RETURNING W-RETURN

Return codes

Table: Return codes (AAL2GenMessageDeactivationICSF)
Code	Meaning	Code	Meaning
0	Success	1267	Invalid message vector length
412	Invalid checksum (software)	1268	Invalid message vector version
413	Invalid Base64 format	1274	Invalid message protocol version
414	Invalid checksum (HSM)	1275	Invalid message protection type
900	Invalid session context handle	1286	Invalid payload key pointer
908	HSM key not found	1288	Invalid serial number prefix
951	Invalid HSM key type for HSM decryption	1302	AES CTR encryption failed
1118	Unsupported BLOB	1307	Invalid deactivation message pointer
1119	Unsupported payload key BLOB	1308	Invalid deactivation message length pointer
1266	Invalid message vector pointer