Activation Message 2 and Digipass instance generation

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

Activation Message 2 and Digipass instance 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.

AAL2GenMessageActivation2ICSF

Function prototype

aat_int32 AAL2GenMessageActivation2ICSF (
                               TDigipassBlob    *DPMAData,
                               TKernelParms     *CallParms,
                               aat_ascii        *aStorageKeyNameIn,
                               aat_ascii        *aInitialVectorIn,
                               aat_ascii        *PKBlob,
                               aat_ascii        *StaticVector,
                               aat_ascii        *MessageVector,
                               aat_ascii        *DeviceID,
                               aat_int32        *pSeqNum,
                               aat_ascii        TokenType [6],
                               aat_int16        *Appl_count,
                               aat_ascii        Serial_Appli [8][23],
                               aat_ascii        AuthMode [8][3],
                               TDigipassBlob    DPData [8],
                               aat_ascii        *Activation2Message,
                               aat_ascii        *Activation2MessageLength);

Description

This function is used to generate an Activation Message 2 from the master activation application (the license), the payload key BLOB, the static vector, the message vector, and the device ID provided. This Activation Message 2 allows activating a Digipass instance of a license into the device.

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 used with this function only if the Secure Channel feature has been ordered (configured by OneSpan at the time of order). No payload key BLOB must be used (parameter NULL or empty string) if the Secure Channel feature has not been ordered.

In case of success, this function will also generate the new Digipass instance application BLOBs, directly bound to the specific device ID provided.

This function uses a new sequence number each time it successfully generates a new Digipass instance for a given license. The number of instances that can be issued from a license is limited to the threshold defined between 1 and 99 for the license (the sequence number threshold value; it can be obtained during the import of the master activation application).

If the instances exceed the defined sequence number threshold for a given license, the function will reject the generation attempt and it will fail.

Parameters

Table: Parameters (AAL2GenMessageActivation2ICSF)
Type	Name	Use	Description
TDigipassBlob	DPMAData	I/O	Digipass master activation application BLOB of the Digipass serial number license that will be used for the activation. 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.
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 *	PKBlob	I	Contains the payload key BLOB of the Digipass serial number to activate. Mandatory if the Secure Channel feature has been ordered. Must be NULL or an empty string if the Secure Channel feature has not been ordered.
aat_ascii *	StaticVector	I	Software Digipass parameter settings, up to 4094 characters, null-terminated.
aat_ascii *	MessageVector	I	A string of up to 26+1 characters containing the message parameter settings, null-terminated (obtained during import).
aat_ascii *	DeviceID	I	Hexadecimal string containing the device ID value of the Digipass device to bind with (8 hexadecimal characters), obtained after the device code validation.
aat_int32 *	pSeqNum	O	Contains in output the sequence number of the generated Digipass instance (from 1 to 99).
aat_ascii[6]	TokenType	O	An output string of 5+1 characters, null-terminated. It contains the Digipass type name given to the Digipass instance. Will return a Digipass type of the form TYPxx with xx representing the device type coded on two decimal digits e.g. TYP07.
aat_int16 *	Appl_count	O	Number of Digipass applications returned. Points to a short integer where the function returns the number of applications found.
aat_ascii[8][23]	Serial_Appli	O	Set of up to 8 x 22+1 character strings, null-terminated, each composed of the 10-character license serial number concatenated with the 12-character application name. Each array entry represents the logical instance of a Digipass cryptographic application with its unique secrets and parameters. The application name part will end with the sequence number coded on two decimal digits e.g. APPL1 03.
aat_ascii[8] [3]	AuthMode	O	Set of up to 8 x 2+1 character strings, null-terminated. Defines each returned authenticator application authentication mode. RO: Response-Only CR: Challenge/Response SG: Signature MM: Multi-Mode UL: Unlock V2 Signature-mode devices may also be used for Challenge/Response authentication if they are programmed to accept a single input data field.
TDigipassBlob[8]	DPData	O	Up to 8 authenticator application BLOBs of the Digipass instance. Upon return from the function call, these BLOBs must be written to the application database.
aat_ascii *	Activation2Message	O	String of up to 124+1 hexadecimal characters, null-terminated. It contains the Activation Message 2 which is necessary during the activation process to provision the Digipass keys and the payload key to the Digipass device.
aat_int32 *	Activation2MessageLength	I/O	In input, this parameter must indicate the size of the allocated buffer for the Activation2Message parameter (recommended 125 bytes). In output, this parameter indicates the length of the Activation2Message string (without the null-terminated character).

COBOL calling convention

Entry point: AA2GM2IC
02   W-MA-BLOB           PIC X(248).
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-STATIC-VECTOR     PIC X(4094).
02   W-MSGVECTOR         PIC X(27).
02   W-PKBLOB            PIC X(89).
02   W-APPL-COUNT        PIC 9(4) USAGE BINARY.
02   W-DEVICE-ID         PIC X(9).
02   W-SEQNUM            PIC 9(8) USAGE BINARY.
02   W-TOKEN-TYPE        PIC X(6).
02   W-SERIAL-APPS.
     03  W-SERIALAPP     PIC X(23) OCCURS 8.
02   W-AUTH-MODES.
     03  W-AUTHMODE      PIC X(3) OCCURS 8.
02   W-DP-BLOBS.
     03  W-DPDATA        PIC X(248) OCCURS 8.
02   W-ACT2MSG           PIC X(85).
02   W-ACT2MSG-LENGTH    PIC 9(8) USAGE BINARY VALUE 85.
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 'AA2GM2IC'.
. . .
     CALL W-API-NAME USING
           BY REFERENCE W-MA-BLOB
           BY REFERENCE W-KERNELPARMS
           BY REFERENCE W-STORAGEKEY
           BY REFERENCE W-INITVECTOR
           BY REFERENCE W-PKBLOB
           BY REFERENCE W-STATIC-VECTOR
           BY REFERENCE W-MSGVECTOR
           BY REFERENCE W-DEVICE-ID
           BY REFERENCE W-SEQNUM
           BY REFERENCE W-TOKEN-TYPE
           BY REFERENCE W-APPL-COUNT
           BY REFERENCE W-SERIAL-APPS
           BY REFERENCE W-DP-BLOBS
           BY REFERENCE W-ACT2MSG
           BY REFERENCE W-ACT2MSG-LENGTH
           RETURNING W-RETURN

Return codes

Table: Return codes (AAL2GenActivationMessage2ICSF)
Code	Meaning	Code	Meaning
0	Success	1272	Invalid message body type
412	Invalid checksum (software)	1274	Invalid message protocol version
413	Invalid Base64 format	1275	Invalid message protection type
414	Invalid checksum (HSM)	1277	Invalid device ID pointer
537	Invalid static vector pointer	1279	Invalid device ID
545	Invalid static vector length	1285	Master key derivation failed
570	Invalid static vector version	1286	Invalid payload key pointer
571	Invalid application index in static vector	1290	Invalid sequence number pointer
574	Invalid serial number prefix in SV	1291	Invalid application count pointer
807	Serial number not equal	1292	Sequence number threshold reached
900	Invalid session context handle	1293	Invalid sequence number
908	HSM key not found	1294	Digipass key derivation failed
951	Invalid HSM key type for HSM decryption	1295	Invalid Digipass instance SM application in static vector
1000	Function does not support EMV-CAP	1296	Key wrapping failed
1009	Corrupt data received	1297	Invalid static vector
1019	Missing mandatory data	1298	Invalid Digipass instance application in static vector
1025	Buffer too small	1302	AES CTR encryption failed
1118	Unsupported BLOB	1310	Invalid payload key type
1119	Unsupported payload key BLOB	1311	Null Digipass data
1264	Invalid master application	1312	Null serial number
1265	Invalid master application data pointer	1313	Null authentication mode
1266	Invalid message vector pointer	1314	Null token type
1267	Invalid message vector length	1317	Secure Channel supported. Payload key BLOB is mandatory
1268	Invalid message vector version	1318	Secure Channel not supported. Payload key BLOB has to be NULL or empty string
1270	Invalid activation message pointer	-1501	Memory allocation failed
1271	Invalid activation message length pointer