--- title: "AAL2GenActivationDataRndKeyICSF" slug: "a3s-cppprg-icsf-zos-aal2genactivationdatarndkeyicsf-4-0" updated: 2026-11-11T10:02:33Z published: 2026-11-11T10:02:33Z canonical: "docs.onespan.com/a3s-cppprg-icsf-zos-aal2genactivationdatarndkeyicsf-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. # AAL2GenActivationDataRndKeyICSF ## Function prototype ```cpp aat_int32 AAL2GenActivationDataRndKeyICSF ( TDigipassBlob* DPData[8], aat_int16* Appl_Count, aat_ascii* aStorageKeyNameIn, aat_ascii* aInitialVectorIn, TKernelParms* CallParms aat_ascii* aStaticVectorIn,, aat_ascii* aSharedData, aat_ascii* aAlea, aat_int32* ActivationFlags, aat_ascii* aSerialNumberSuffix, aat_ascii* aXFAD, aat_ascii* aXERC); ``` ## Description This function generates software Digipass activation data with random Digipass key generation: - Either an activation code can be used for an offline activation workflow (offline activation mode) - Or an encrypted full activation data (XFAD)), that can be used for an online activation workflow (Online Activation Mode).. For software Digipass authenticators based on Digipass SDK 4.0 or later, the activation mode depends on the content of the ActivationFlags input parameter pointer. For earlier software Digipass authenticators based on the Digipass SDK prior to version 4.0, by default, the activation mode depends on the static vector configuration and content. It can be forced to offline activation mode, setting the appropriate flag in the ActivationFlags input parameter pointer. This function can also generate: - Either an event reactivation counter (ERC), if both the aSharedData and aAlea parameters are set to NULL, or - An encrypted event reactivation counter (XERC), if the aSharedData and/or aAlea parameters are used. > For software Digipass authenticators based on Digipass SDK prior to version 4.0, it is not allowed to use aSharedData and/or aAlea for the offline activation mode. This function extends the former AAL2GenActivationCodeXErc function, adding the generation of a new random Digipass key. > To generate activation data for a software Digipass authenticator using this function, it is mandatory to provide all the corresponding customer authenticator application BLOBs. The function will fail if not all customer authenticator application BLOBs of the related software Digipass authenticators are provided. > > In addition, a new random key will be generated for the software Digipass authenticator and will replace the previous one. > > The generated [encrypted] activation code (or [X]FAD) will be related to the new software Digipass key, and the authenticator application BLOBs will be updated with the new software Digipass key. > > Buffers must be mandatorily allocated for aSerialNumberSuffix, aXFAD, and aXERC. ## Parameters | Type | Name | Use | Description | | --- | --- | --- | --- | | TDigipassBlob * [8] | DPData | I/O | Array of authenticator application BLOB pointers. Upon return from the function call, these BLOBs must be rewritten to the application database to reflect the changes. | | aat_int16 | Appl_count | I | Number of applications in the authenticator application BLOB array. (1 to 8) | | 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 * | aStatic VectorIn | I | Software Digipass parameter settings, up to 4094 characters, null-terminated. | | aat_ascii * | aSharedData | I | Data used to encrypt the activation data. Up to 512* characters, null-terminated. Set to NULL if no shared data used by the software Digipass activation process. *Shared data plus alea must not exceed 512 characters. | | aat_ascii * | aAlea | I | Encryption diversifier pseudo-randomly generated. Up to 512* characters. Set to NULL if no alea is used by the software Digipass activation process. *Shared data plus alea must not exceed 512 characters. | | aat_int32 * | Activation Flags | I | Integer value that specifies the activation mode used for generating activation data (online or offline activation mode.) The ActivationFlags value can be either set to 0x0 or 0x1. [Table: Possible ActivationFlags pointed values (AAL2GenActivationDataRndKeyICSF)](/secsdks/docs/a3s-cppprg-icsf-zos-aal2genactivationdatarndkeyicsf-4-0#TAB_possible_ActivationFlags_pointed_values) lists the possible values for ActivationFlags. | | aat_ascii * | aSerial NumberSuffix | O | String of up to 14+1 null-terminated digits representing the last 7 digits of the Digipass serial number. 14+1 null-terminated digits in case of software Digipass authenticators based on the Digipass SDK prior to version 4.0 (SN suffix formatted with inserted 0). 7+1 null-terminated digits in case of software Digipass authenticators based on the Digipass SDK 4.0 or higher. aSerialNumberSuffix buffer must have at least 15 bytes allocated. | | aat_ascii * | aXFAD | O | String of up to 4142+1 characters, null-terminated. This parameter holds either the [encrypted] activation code (in case of offline mode) or the [encrypted] full activation data ([X]FAD) (in case of online mode). The aXFAD buffer must have at least 4143 bytes allocated. | | aat_ascii * | aXERC | O | String of up to 91+1 characters, null-terminated. If this parameter is NULL, the event reactivation counter will not be generated. This parameter holds either the event reactivation counter (ERC) (if both the SharedData and Alea parameters are set to NULL) or the encrypted event reactivation counter (XERC) (if the SharedData and/or Alea parameters are not set to NULL). The aXERC buffer must have at least 92 bytes allocated. | | Flag | Value | Description | | --- | --- | --- | | ACTV_DEFAULT | 0x00000000 | Online activation mode for software Digipass authenticators based on the Digipass SDK 4.0 or later (function generates an [X]FAD). The activation mode configured in the static vector for software Digipass authenticators based on the Digipass SDK prior to version 4.0, online or offline (the function generates an [X]FAD or an activation code depending on static vector content). | | ACTV_OFFLINE | 0x00000001 | Offline activation mode (function generates an [encrypted] activation code). | ## COBOL calling convention ```custom Entry point: AA2GADIC 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-STORAGEKEY PIC X(65). 02 W-INITVECTOR PIC X(17). 02 W-SHARED-DATA PIC X(33). VALUE Z'6C45D98F7EFDD207760287BFE7D66959'. 02 W-BLOB-TABLE. 03 W-BLOB PIC X(248) OCCURS 8. 02 W-BLOB-PTR-TABLE. 03 W-BLOB-PTR USAGE POINTER OCCURS 8. 02 W-APPL-COUNT PIC S9(4). 02 W-RETURN PIC S9(8) USAGE BINARY. 02 W-API-NAME PIC X(8) VALUE 'AA2GADIC. 02 W-STATIC-VECTOR PIC X(1024) VALUE SPACES. 02 W-ACTIVATION-FLAG PIC 9(8) USAGE BINARY VALUE 0. 02 W-SERIAL-SUFFIX PIC X(15) VALUE SPACES. 02 W-XFAD PIC X(4143) VALUE SPACES. 02 W-XERC PIC X(92) VALUE SPACES. . . . SET W-BLOB-PTR(n) TO ADDRESS OF W-BLOB(n). CALL W-API-NAME USING BY REFERENCE W-BLOB-PTR-TABLE BY VALUE W-APPL-COUNT BY REFERENCE W-KERNELPARMS BY REFERENCE W-STORAGE-KEY-LABEL BY REFERENCE W-INITIAL-VECTOR BY REFERENCE W-STATIC-VECTOR BY REFERENCE W-SHARED-DATA BY REFERENCE OMITTED BY VALUE W-ACTIVATION-FLAG BY REFERENCE W-SERIAL-SUFFIX BY REFERENCE W-XFAD BY REFERENCE W-XERC RETURNING W-RETURN ``` ## Return codes | Code | Meaning | Code | Meaning | | --- | --- | --- | --- | | 0 | Success | 571 | Invalid application index in static vector | | 147 | Invalid ActivationCode pointer | 572 | Missing application key type in static vector | | 164 | Invalid serial number suffix pointer | 573 | Serial number suffix not decimal | | 412 | Invalid checksum (software) | 574 | Invalid serial number prefix in SV | | 413 | Invalid Base64 format | 575 | Invalid event reactivation counter pointer | | 414 | Invalid checksum (HSM) | 576 | Digipass data does not match with SV | | 510 | Invalid Digipass data pointer | 578 | Invalid BLOB status | | 537 | Invalid static vector pointer | 579 | Alea or shared data not allowed | | 543 | Activation code generation not supported | 807 | Serial number not equal | | 545 | Invalid static vector length | 808 | Invalid application count value (1 to 8.) | | 546 | Invalid activation code format in static vector | 900 | Invalid session context handle | | 547 | Alea is too long | 908 | HSM key not found | | 548 | Shared data too long | 951 | Invalid HSM key type for HSM decryption | | 549 | Alea + shared data too long | 1000 | Function does not support EMV-CAP | | 567 | Invalid activation flags value | 1103 | Unlock Version 2 not supported | | 568 | Invalid DP+ application in Digipass data | 1118 | Unsupported BLOB | | 569 | Invalid application name in Digipass data | -1501 | Memory allocation failed | | 570 | Invalid static vector version | | |