--- title: "AAL2VerifyPasswordICSF" slug: "a3s-cppprg-icsf-zos-aal2verifypasswordicsf-4-0" updated: 2026-11-11T09:52:07Z published: 2026-11-11T09:52:07Z canonical: "docs.onespan.com/a3s-cppprg-icsf-zos-aal2verifypasswordicsf-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. # AAL2VerifyPasswordICSF ## Function prototype (aal2sdk.h) ```cpp aat_int32 AAL2VerifyPasswordICSF ( TDigipassBlob* DPBlob, TKernelParms* CallParms, aat_ascii* aStorageKeyNameIn, aat_ascii* aInitialVectorIn, aat_ascii* aResponseIn, aat_ascii* aChallengeIn, aat_ascii* ReturnHostCode, aat_int32* ReturnHostCodeLength); ``` ## Description The AAL2VerifyPasswordICSF function performs Digipass owner's authentication by controlling if a given Digipass-generated dynamic password is valid for a specified Digipass described by its application BLOB DPBlob. Optionally, the previously generated Challenge is also passed to this function. ### Return host code In addition, a new feature is present that allows a client to authenticate back the Host server that validated the dynamic password. It facilitates a two way authentication process. The server validates the user's dynamic password and returns a host code as an acknowledgement that the user is able to verify on its Digipass. This allows the end user to be sure that the host server is the correct one. This function is particularly useful for web implementations. ### GO1 integration This function can also be used for static PIN management for Digipass GO 1 or Digipass GO 3. In this case a password could have different appearances as in the examples below: - **No static PIN.** Regular password authentication request **89574526** - **Static PIN.** Same authentication request in combination with static PIN usage **1234****89574526**, the static PIN is entered before the dynamic password, the AAL2VerifyPasswordICSF function will evaluate static PIN and dynamic password in sequence. - **Static PIN Change.** Same authentication request in combination with static PIN usage and a request for PIN change **12348957452643214321**. The static PIN is entered before the dynamic password and both New PIN + New PIN confirmation are entered after. The AAL2VerifyPasswordICSF function will evaluate static PIN and dynamic password in sequence then process for a PIN change. This function allows the customer to address the HSM storage key by name and to specify an initial vector. The initial vector is used during the 3DES/AES decryption/encryption of the sensitive data of the authenticator application BLOB. ### Score-based Digipass For Digipass devices that integrate the score-based algorithm, Authentication Suite Server SDK performs a score-based authentication which allows retrieving the Digipass scoring value. Once Authentication Suite Server SDK has successfully validated the password, it returns either SUCCESS or SUCCESS with the relevant scoring warning code. See the list of return codes in [Table: Return codes (AAL2VerifyPasswordICSF)](/secsdks/docs/a3s-cppprg-icsf-zos-aal2verifypasswordicsf-4-0#tab_Return_codes) for more details. ## Parameters > The memory management of the output parameters must be performed by the calling function. | Type | Name | Use | Description | | --- | --- | --- | --- | | TDigipassBlob * | DPBlob | I/O | authenticator application BLOB. | | 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 * | aResponseIn | I | Up to 16+24+1 numeric or hexadecimal characters, left justified, null terminated or right padded with spaces. This is the dynamic password generated by the Digipass. | | aat_ascii * | aChallengeIn | I | Up to 16+1 numeric characters, left justified, null terminated or right padded with spaces. This parameter holds the challenge that may have been proposed to the user to generate CodeToVerify. If no challenge was generated, this parameter should be NULL. | | aat_ascii * | ReturnHostCode | O | String of 7 or 8 numeric characters which the user needs to enter into the Digipass authenticator to unlock it (recommended buffer size is 9 bytes). | | aat_int32 * | ReturnHostCodeLength | O | Pointer to a long integer that will contain the length of the return host code which has been generated. | ## COBOL calling convention ```custom Entry point: AA2VVPIC 02 W-BLOB PIC X(248). 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-HOSTCODE PIC X(17). 02 W-HOSTCODE-LENGTH PIC 9(8) USAGE BINARY. 02 W-RETURN PIC S9(8) USAGE BINARY. 02 W-PASSWORD PIC X(17). 02 W-CHALLENGE PIC X(17). 02 W-STORAGEKEY PIC X(65). 02 W-INITVECTOR PIC X(17). 02 W-API-NAME PIC X(8) VALUE 'AA2VVPIC'. . . . CALL W-API-NAME USING BY REFERENCE W-BLOB BY REFERENCE W-KERNELPARMS BY REFERENCE W-STORAGEKEY BY REFERENCE W-INITVECTOR BY REFERENCE W-PASSWORD BY REFERENCE W-CHALLENGE BY REFERENCE W-HOSTCODE BY REFERENCE W-HOSTCODE-LENGTH RETURNING W-RETURN ``` ## Return codes | Code | Meaning | Code | Meaning | | --- | --- | --- | --- | | 0 | Success | 802 | Change password mandatory | | 1000 | Success with context warning[[1]](/secsdks/docs/a3s-cppprg-icsf-zos-aal2verifypasswordicsf-4-0#Cite_1) | 803 | New password too short | | 1000 | Success with user warning[[1]](/secsdks/docs/a3s-cppprg-icsf-zos-aal2verifypasswordicsf-4-0#Cite_1) | 804 | New password too long | | 1000 | Success with user & context warning[[1]](/secsdks/docs/a3s-cppprg-icsf-zos-aal2verifypasswordicsf-4-0#Cite_1) | 900 | Invalid session context handle | | 1000 | Success with platform warning[[1]](/secsdks/docs/a3s-cppprg-icsf-zos-aal2verifypasswordicsf-4-0#Cite_1) | 908 | HSM key not found | | 1000 | Success with platform & context | 951 | Invalid HSM key type for HSM decryption | | 1000 | Success with platform & user warning[[1]](/secsdks/docs/a3s-cppprg-icsf-zos-aal2verifypasswordicsf-4-0#Cite_1) | 1039 | Invalid response length with DP algorithm | | 1000 | Success with platform & user & context | 1040 | Invalid host code length with DP algorithm | | 1 | Code not verified | 1103 | Unlock Version 2 not supported | | 2 | Static password validation failed | 1116 | Response check digit not allowed | | 130 | Invalid response pointer | 1117 | Challenge check digit not allowed | | 131 | Missing required challenge | 1118 | Unsupported BLOB | | 132 | Unsupported token type | -101 | Challenge too short | | 140 | Challenge corrupted | -102 | Challenge too long | | 201 | Code replay attempt | -103 | Challenge check digit wrong | | 202 | Identification error threshold reached | -105 | Challenge minimum length not allowed | | 205 | Inactive days reached | -106 | Challenge maximum length not allowed | | 208 | Application disabled | -107 | Challenge number wrong | | 412 | Invalid checksum (software) | -108 | Challenge character invalid | | 413 | Invalid Base64 format | -201 | Response length out of bounds | | 414 | Invalid checksum (HSM) | -202 | Response too short | | 510 | Invalid Digipass data pointer | -203 | Response too long | | 600 | Invalid Gordian root information | -204 | Response check digit wrong | | 601 | Invalid Gordian today information | -205 | Response character not decimal | | 602 | Invalid Gordian tomorrow information | -206 | Response character not hexadecimal | | 603 | Invalid Gordian stimulus information | -207 | Response character set not specified | 1. Specific score-based authentication code (see [Score-based DIGIPASS](/secsdks/docs/a3s-cppprg-icsf-zos-aal2verifypasswordicsf-4-0#scorebased-digipass))