This chapter 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.
Function prototype
aat_int32 AAL2GenMessageRequest (
aat_ascii *PKBlob,
TKernelParms *CallParms,
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 (AAL2GenMessageRequest) | 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 * | 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). |
Return codes
Table: Return codes (AAL2GenMessageRequest) | Code | Meaning | Code | Meaning |
|---|
| 0 | Success | 1286 | Invalid payload key pointer |
| 412 | Invalid checksum | 1288 | Invalid serial number prefix |
| 413 | Invalid Base64 format | 1289 | Invalid serial number suffix |
| 1118 | Unsupported BLOB | 1302 | AES CTR encryption failed |
| 1119 | Unsupported payload key BLOB | 1303 | Invalid request message pointer |
| 1025 | Buffer too small | 1304 | Invalid request message length pointer |
| 1266 | Invalid message vector pointer | 1305 | Invalid request body pointer |
| 1267 | Invalid message vector length | 1306 | Invalid request body length |
| 1268 | Invalid message vector version | 1334 | Transaction request not supported |
| 1274 | Invalid message protocol version | 1335 | Invalid payload key type in payload key data |
| 1275 | Invalid message protection type | 1336 | Inconsistent payload key type between payload key data and message vector |
| 1285 | Master key derivation failed | | |