Request message generation

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

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.

AAL2GenMessageRequestICSF

Function prototype

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

Table: Parameters (AAL2GenMessageRequestICSF)
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

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

Table: Return codes (AAL2GenMessageRequestICSF)
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