--- title: "AAL2GenMessageRequestICSF" slug: "a3s-cppprg-icsf-zos-aal2genmessagerequesticsf-4-0" updated: 2026-11-11T10:00:40Z published: 2026-11-11T10:00:40Z canonical: "docs.onespan.com/a3s-cppprg-icsf-zos-aal2genmessagerequesticsf-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. # AAL2GenMessageRequestICSF > The request message generation functionality is applicable: > > - To hardware or software Digipass authenticators compliant with the multi-device two-step activation (in the context of multi-device licensing) and if the Secure Channel feature has been ordered (configured by OneSpan at the time of order). > - To hardware Digipass authenticators based on the single-device licensing model and able to perform operations based on the Secure Channel protocol. > > For more information, refer to the [Authentication Suite Server SDK Product Guide](/secsdks/docs/a3s-product-guide-4-0). ## Function prototype ```cpp aat_int32 AAL2GenMessageRequestICSF ( aat_ascii *PKBlob, TKernelParms *CallParms, aat_ascii *aStorageKeyNameIn, aat_ascii *aInitialVectorIn, aat_ascii *MessageVector, aat_ascii *RequestBody, aat_ascii *RequestMessage, aat_int32 *RequestMessageLength); ``` ## Description This function is used to generate a request message from a clear request body, using the payload key embedded into the payload key BLOB. The payload key BLOB must be the one corresponding to the Digipass serial number the request message will target. > The request message generation is only applicable to hardware and software Digipass compliant with the Secure Channel protocol. ## Parameters | 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 (in case of the multi-device licensing model) or that has been imported for the Digipass authenticator with a particular serial number license (in case of single-device licensing model). The payload key BLOB parameter is mandatory only if the information message is protected (encrypted and/or signed); can be NULL or empty if the information message is not protected (neither encrypted nor signed). | | 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_ascii * | RequestBody | I | Hexadecimal character string containing the clear request body to use for generating the request message. The string length must be a multiple of 2 with a maximum length of 1024 characters. | | aat_ascii * | RequestMessage | O | A string of up to 1070+1 hexadecimal characters, null-terminated. In case of a successful operation, this parameter contains the generated RequestMessage. | | aat_int32 * | RequestMessageLength | I/O | In input, this parameter must indicate the size of the allocated buffer for the RequestMessage parameter (recommended 1071 bytes). In output, this parameter indicates the length of the RequestMessage string (without the null-terminated character). | ## COBOL calling convention ```custom Entry point: AA2GMRIC 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-REQBODY PIC X(1024). 02 W-REQMSG PIC X(1071). 02 W-REQMSG-LENGTH PIC 9(8) USAGE BINARY VALUE 1071. 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 'AA2GMRIC'. . . . 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-REQBODY BY REFERENCE W-REQMSG BY REFERENCE W-REQMSG-LENGTH RETURNING W-RETURN ``` ## Return codes | Code | Meaning | Code | Meaning | | --- | --- | --- | --- | | 0 | Success | 1268 | Invalid message vector version | | 412 | Invalid checksum (software) | 1274 | Invalid message protocol version | | 413 | Invalid Base64 format | 1275 | Invalid message protection type | | 414 | Invalid checksum (HSM) | 1286 | Invalid payload key pointer | | 900 | Invalid session context handle | 1288 | Invalid serial number prefix | | 908 | HSM key not found | 1302 | AES CTR encryption failed | | 951 | Invalid HSM key type for HSM decryption | 1303 | Invalid request message pointer | | 1118 | Unsupported BLOB | 1304 | Invalid request message length pointer | | 1119 | Unsupported payload key BLOB | 1305 | Invalid request body pointer | | 1266 | Invalid message vector pointer | 1306 | Invalid request body length | | 1267 | Invalid message vector length | | |