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.
Function prototype
aat_int32 AAL2GenMessageActivation2 (
TDigipassBlob *DPMAData,
aat_ascii *PKBlob,
TKernelParms *CallParms,
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 a Activation Message 2 from themaster 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
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
Table: Parameters (AAL2GenMessageActivation1) | 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 change |
| 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. |
| TKernelParms * | CallParms | I | Structure of runtime parameters to use during this function call. |
| aat_ascii * | StaticVector | I | Software Digipass parameter settings, up to 4094 characters, null-terminated. |
| aat_ascii * | MessageVector | I | String of up to 26+1 characters containing the message parameter settings , null-terminated (obtained during import). |
| aat_ascii * | DeviceID | I | Hexadecimal string containing thedevice 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 Digipasstype of the form 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 NOTE: 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). |
Return codes
Table: Return codes (AAL2GenMessageActivation1) | Code | Meaning | Code | Meaning |
|---|
| 0 | Success | 1279 | Invalid device ID |
| 412 | Invalid checksum | 1285 | Master key derivation failed |
| 413 | Invalid Base64 format Invalid serial number prefix | 1286 | Invalid payload key pointer |
| 537 | Invalid static vector pointer | 1288 | Invalid serial number prefix |
| 545 | Invalid static vector length | 1289 | Invalid serial number suffix |
| 570 | Invalid static vector version | 1290 | Invalid sequence number pointer |
| 571 | Invalid application index in static vector | 1291 | Invalid application count pointer |
| 574 | Invalid serial number prefix in SV | 1292 | Sequence number threshold reached |
| 807 | Serial number not equal | 1293 | Invalid sequence number |
| 1000 | Function does not support EMV-CAP | 1289 | Invalid serial number suffix |
| 1009 | Corrupt data received | 1295 | Invalid Digipass instance SM application in static vector |
| 1019 | Missing mandatory data | 1296 | Key wrapping failed |
| 1118 | Unsupported BLOB | 1297 | Invalid static vector |
| 1119 | Unsupported payload key BLOB | 1298 | Invalid Digipass instance application in static vector |
| 1025 | Buffer too small | 1302 | AES CTR encryption failed |
| 1264 | Invalid master application | 1310 | Invalid payload key type |
| 1265 | Invalid master application data pointer | 1311 | Null Digipass data |
| 1266 | Invalid message vector pointer | 1312 | Null serial number |
| 1267 | Invalid message vector length | 1313 | Null authentication mode |
| 1268 | Invalid message vector version | 1314 | Null token type |
| 1270 | Invalid activation message pointer | 1317 | Secure Channel supported. Payload key BLOB is mandatory |
| 1271 | Invalid activation message length pointer | 1318 | Secure Channel not supported. Payload key BLOB has to be NULL or empty string |
| 1272 | Invalid message body type | 1332 | Activation 2 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 |
| 1277 | Invalid device ID pointer | -1501 | Memory allocation failed |