--- title: "AAL2GenMessageActivation2ICSF" slug: "a3s-cppprg-icsf-zos-aal2genmessageactivation2icsf-4-0" updated: 2026-11-11T10:00:40Z published: 2026-11-11T10:00:40Z canonical: "docs.onespan.com/a3s-cppprg-icsf-zos-aal2genmessageactivation2icsf-4-0" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.onespan.com/llms.txt > Use this file to discover all available pages before exploring further. # AAL2GenMessageActivation2ICSF > 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](/secsdks/docs/a3s-product-guide-4-0). ## Function prototype ```cpp 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](/secsdks/docs/a3s-product-guide-4-0). > 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 | 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 ```custom 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 | 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 | | |