Digipass Adapter [Deprecated]

Functionality

The Digipass adapter allows TrustBuilder to execute various types of Digipass requests. The basic operations include authenticating, generating challenges and changing the static pin. The adapter also provides a few utility services, such as generating an activation token. The adapter relies on the VACMAN Controller library, which is actually a wrapper around a native library.

Prerequisites

LDAP Adapter

An LDAP-adapter must be configured in the workflow pointing to an LDAP containing the Digipass BLOB-information. This adapter will be used during the configuration of the Digipass adapter and will act as the "storage adapter", in order to get/write the Digipass BLOB from/to the LDAP.

Load DPX

Please read more in the chapter "Load DPX".

Install Vacman Controller Library

Please read more in the chapter "Install Vacman Controller".

Configuration

AdapterUniqueID

Unique name assigned to this adapter; the name is used to reference the adapter in the workflow. The ID has following requirements:

START with a letter or _ (underscore)
FOLLOWED by a combination of following characters: Letter, Number, '.' (dot), '-' (dash), '_' (underscore)

Storage adapter

Contain the name of the LDAP-adapter as created in the prerequisites

Context

Used to locate the digipass data within a larger environment. In case of LDAP this may refer to a substructure (e.g. context="ou=digipass,o=securit,c=be")

Kernel parameters

The runtime parameters are described in detail in the VACMAN Controller Product Guide. The values in the example above correspond to the default values as specified in the VACMAN Controller Product Guide. (The SynchronizationWindow parameter specifies hours, rather than minutes.)

The product guide specifies 1 as a minimum value for the TransportKeyId parameter, although the sample programs use a value of 0.

Parameter	Default	Description
CheckChallenge	1	0: No challenge checking 1: Chek the parameter then verify with the DPDate Challenge
CheckInactiveDays	0	Acceptable number of days of user/token inactivity. Past this number, returncode 205 will be genrated and the digipass will have to be reset. 0 = disabled
DeriveVextor	0	Vector used to make the data encryption unique for a host
EventWindow	100	Expressed in number of iterations This represents the acceptable event counter difference between digipass and host. This parameter applies only for event based operating modes
GMTAdjustment	0	GMT Time adjustment to perform in case the C language gmtime function doesn' t give an accurate value
HSMSLotId	0	HSM Slot Id used to store Storage Key and Transport Key
IdentificationTreshold	0	Number of successive identification errors that will cause server-side locking of the digipass. When the specified number is reached, return code 202 is sent to the caller. 0=disabled
IdentificationTimeWindow	100	This size determines the acceptable time difference between a digipass and the host system for identification function. This difference is adjusted to the last knows shift for each token. the maximum drift correction acceptance is 1 second per 6 hour period. Since version 3.5.0.3, this parameter can be set to be dynamic or static. If dynamic, the size of the window will increase as the time passes since last use of the DIGIPASS. Because of this feature, the Dynamic window can be set smaller than if Static window was used. TW_DYNAMIC_WINDOWS (in aal2sdk.h) is a bitmask indicator that can be used to show whether ITimeWindow is Dynamic or Static.
OnlineSignature	0	Level of online signature 1: several signatures are allowed in the same timestep (except identical successive ones) 2: only one signature per timeStep is allowed 3: for event based signature, use the deffered data input parameter
SignatureTreshold	0	Number of successive signature errors that will cause server-side locking of the digipass. When the specified number is reached; return code 203 is sent to the caller. 0=disabled
StorageDeriveKey1	0	Derivation key part 1 used to make data encryption unique for a host.
StorageDeriveKey2	0	Derivation key part 2 used to make data encryption unique for a host.
StorageDeriveKey3	0	Derivation key part 3 used to make data encryption unique for a host.
StorageDeriveKey4	0	Derivation key part 4 used to make data encryption unique for a host.
StorageKeyId	0	Key Id used to read (Decrypt) DIGIPASS Blob from database.
TransportKeyId	0xFFFFFFFF	Key Id used to read (Decrypt) DIGIPASS Blob from database.
SynchronizationWindow	6 hours	The Initial Time Synchronization Window - for the first verification of a DIGIPASS. This parameter allows the verification process to calculate the initial deviation between a DIGIPASS time and the VACMAN Controller GMT Time. IMPORTANT: This value is expressed in hours or minutes.
ParamCount	N.A.	Not implemented by TrustBuilder
STImeWindow	N.A.	Not implemented by TrustBuilder
DiagLevel	N.A.	Not implemented by TrustBuilder

Workflow Settings

A request for the adapter is prepared by specifying the following properties/scripts in the adapter activity:

Input Property: the variable containing the instructions the adapter have to execute
Output Property: the variable the adapter will store the response in after execution
Before Adapter Script: script that will be executed before calling the adapter
After Adapter Script: script that will be executed after the adapter fulfilled its task

Request - API

Activation

DigipassActivateTokenQARequest The DigipassActivateTokenQARequest allows verifcation of an OTP or an answer to a secret question The application / user id combo should be linked to a token in the storage containing a digipass blob.

digipassAdapterActivateTokenQARequest(application,userId,password,challenge,qaData)

Application - Non-null,non-empty String.
UserID - Non-null, non-empty String.
Password - Non-null, non-empty String.
Challenge - May be specified in case we want to validate a challenge - response authentication; otherwise null String.
QAData - Non-null, non-empty String.

DigipassActivateTokenRequest The DigipassActivateTokenRequest allows verification of an OTP. The application / user id combo should be linked to a token in the storage containing a digipass blob. The digipass blob may be modified by the operation, hence its value is updated in the storage, as is the status of the token if authentication is successful.

digipassAdapterActivateTokenRequest(application,userId,password,challenge)

Application - Non-null, non-empty String.
UserID - Non-null, non-empty String.
Password - Non-null, non-empty String.
Challenge - May be specified in case we want to validate a challenge - response authentication; otherwise may be null String.

Authentication

DigipassAuthenticateRequest The DigipassAuthenticateRequest allows clients to validate a password for given user id in the specified application.

digipassAdapterAuthenticateRequest(application,userId,password,challenge)

Application - Non-null, non-empty String.
UserID - Non-null, non-empty String.
Password - Non-null, non-empty String.
Challenge - maybe null String.
Optionally, a Challenge may be specified in case we want to validate a challenge - response authentication.
The application / user id combo should be linked to a token in the storage containing a digipass blob. The digipass blob may be modified by the operation, hence its value is updated in the storage.

DigipassAuthenticateTokenRequest The DigipassAuthenticateTokenRequest allows clients to validate a password for given token id in the specified application.

digipassAdapterAuthenticateTokenRequest(application,tokenId,password,challenge)

Application - Non-null, non-empty String.
tokenId - Non-null, non-empty String.
Password - Non-null, non-empty String.
Challenge - maybe null String.
Optionally, a Challenge may be specified in case we want to validate a challenge - response authentication.
The application / token id combo should represent a token in the storage containing a digipass blob. The digipass blob may be modified by the operation, hence its value is updated in the storage.

Generate Challenge

DigipassGenerateChallengeRequest The DigipassGenerateChallengeRequest allows clients to generate a challenge for given user in the specified application.

digpassAdapterGenerateChallengeRequest(application,userId)

Application - Non-null, non-empty String.
UserID - Non-null, non-empty String.
The application / user id combo should be linked to a token in the storage containing a digipass blob. The digipass blob may be modified by the operation, hence its value is updated in the storage.

DigipassGenerateChallengeTokenRequest The DigipassGenerateChallengeRequest allows clients to generate a challenge for given token in the specified application.

digipassAdapterGenerateChallengeTokenRequest(application,tokenId)

Application - Non-null, non-empty String.
tokenId - Non-null, non-empty String.
The application / token id combo should represent a token in the storage containing a digipass blob. The digipass blob may be modified by the operation, hence its value is updated in the storage.

Other

DigipassGenerateReregisterUserRequest The DigipassReregisterUserRequest allows clients to generate an activation code for the token linked to given user in the specified application.

digipassAdapterGenerateReRegisterUserRequest(random,applicationName,user,trust)

Alea - Non-null, non-empty String.
Application - Non-null, non-empty String.
User - Non-null, non-empty String.
TrustLevel - Non-null, non-empty int.
The application / user id combo should be linked to a token in the storage containing a digipass blob. The digipass blob may be modified by the operation, hence its value is updated in the storage. If the token is marked as activated generate an activation code using given alea and secret.

DigipassChangePasswordRequest The DigipassChangePasswordRequest allows clients to change the static PIN for given user in the specified application.

digipassAdapterChangePasswordRequest(application,userId,password,newPassword)

Application - Non-null, non-empty String.
UserID - Non-null, non-empty String.
Password - Non-null, non-empty String.
newPassword - Non-null, non-empty String.
The Password consists of the actual password pre-fixed with the static PIN that should be changed. The NewPassword is the new static PIN.
The application / user id combo should be linked to a token in the storage containing a digipass blob. The digipass blob may be modified by the operation, hence its value is updated in the storage.

Response - API

Common Properties The response API can be applied to the variable specified in the “output property” (see “Workflow Settings”): to verify whether the action performed by the adapter was successful, to query for the data returned by the adapter.

All responses have four properties in common:

status Status flag indicating whether the response is ok (0) or not (1).
substatus Response specific number indicating what the problem was, eg. http status code
message Response specific message in case there was a problem (can be null)
rc Return Code, a human readable code based on the substatus

The status flag indicates whether a request was valid yes or no; consequently, the message or return code (rc) can be used to give the end-user a reasonable explanation or send the information to the underlying logging system.

Adapter Specific Properties

activationCode
challenge
hostCode
indexList
qaBlob
qaKey
sharedSecret
reference

Response Codes

Several types of errors may occur. The status field in the response identifies classes of errors. The sub-status field gives more detailed information, such as the VACMAN Controller error.

	Status	Sub-status	RC	Error	Response type
Success	0	0	OK		DigipassResponse
Internal Error	1	14	NO_SHARED_SECRET	No Shared Secret was found
Storage adapter errors	10	12	USER_ASSIGNED_TOKEN_ERROR	Token is already assigned to another user	DigipassResponse
TrustBuilder error	4	1		Internal error	ExceptionResponse
	4	2		Invalid request document	ExceptionResponse
Digipass error	5	1	LIBRARY_ERROR	The aal2sdk library could not not be loaded	DigipassResponse
	5	10	STORAGE_DATA_ERROR	The data in the storage is not consistent	DigipassResponse
	5	11	INACTIVE_TOKEN_ERROR	The token is not marked as active in the storage	DigipassResponse
	5	13	NO_UNASSIGNED_TOKENS_FOUND	No tokens are available anymore to assign to a new user
VACMAN controller error	6			The sub-status contains the VACMAN error (see VACMAN Controller C-C++ Programmer's Guide for error details)	DigipassResponse

Load dpx

In order to use the digipass adapter a couple of steps need to be done

Load the objectClasses in your LDAP

Although other storage adapters are possible, currently ldap is the only one available. In order to work it requires some custom objectClasses.These can be found in the vasco folder of the TB_TOOLS folder. Check your vendor’s documentation on how to import the ldif into your ldap.

Import the DPX files into LDAP

Once the objectClasses are loaded, the tokens available in the DPX file can be imported via the vascoImport script found in the TB_TOOLS folder. For this to work you need to prepare a config file. An example can be found below:

# Type of dpx  [ token | web | mobile ]
type=

# Absolute path to dpx file
dpxfile=

# Key of the DPX file
#key=

# Static vector (only required for web and mobile)
#static_vector=

# Absolute path to activation code (only for mobile)
#activation_code_file=

java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory
java.naming.provider.url=ldap://localhost:389/o=trustbuilder
java.naming.security.authentication=simple
java.naming.security.principal=cn=username
java.naming.security.credentials=password

# Other properties passed to the vascocontroller
CheckInactiveDays=
DeriveVector=
EventWindow=
GMTAdjustment=
HSMSlotId=
IdentificationThreshold=
IdentificationTimeWindow=
OnlineSignature=
SignatureThreshold=
SignatureTimeWindow=
StorageDeriveKey1=
StorageDeriveKey2=
StorageDeriveKey3=
StorageDeriveKey4=
StorageKeyId=
SynchronizationWindow=
TransportKeyId=

Now the program is ready to load the tokens in the ldap. You can launch it depending on the kind of tokens as follows

./vascoImport.sh <config file>

Key, static vector (and activation codes file) should be given by vasco when you’ve received the tokens.

Prepare application server

Since the digipass engine is a external native component within trustbuilder, the so/dll file needs to be on the so called library path of the application server. This can normally be altered in the startup script by modifying the environment variable LD_LIBRARY_PATH

Install Vacman Controller

Vacman Controller Files

Depending on the underlying OS, either one of the following files is required:

Windows: aal2sdk.dll Linux: aal2sdk.so

The files are part of the Vasco Vacman Controller software: http://www.vasco.com/products/server_products/vacman/vacman_controller.aspx

Websphere

The LD_LIBRARY_PATH must be set as an environment variable to the Application server:

Application Servers > [server] > Process Definitions > Environment Entries

Add a new entry:

LD_LIBRARY_PATH /path/to/aal2sdk.so|dll

Example

Request

var obj = workItem.requestObject;

logDebug("switch case for digipass based on: "+obj.ACTION);

switch(obj.ACTION){
    case "AUTHENTICATE":
        workItem.dpRequest = tb.digipassAdapterAuthenticateRequest(obj.APPLNAME,obj.USERNAME,obj.TOKEN,obj.CHALLENGE);
    break;
    case "AUTHENTICATE_BY_SN":
        workItem.dpRequest = tb.digipassAdapterAuthenticateTokenRequest(obj.APPLNAME,obj.TOKENSERIAL,obj.TOKEN,obj.CHALLENGE);
    break;
    case "DP4WEB_ACTIVATE_TOKEN_QA":
        workItem.dpRequest = tb.digipassAdapterActivateTokenQARequest(obj.APPLNAME,obj.USERNAME,obj.TOKEN,obj.CHALLENGE,obj.QA_BLOCK);
    break;
    case "DP4WEB_REREGISTER_USER_QA":
        workItem.dpRequest = tb.digipassAdapterReregisterUserQARequest(obj.ALEA,obj.APPLNAME,obj.USERNAME,obj.TRUST_LEVEL);
    break;
    case "DP4WEB_REGISTER_USER":
        workItem.dpRequest = tb.digipassRegisterUserWeb(obj.ALEA,obj.SHARED_SECRET,obj.USERNAME,obj.APPLNAME,obj.DN);
    break;
}

Response

function processDigipassResponse(workItem){

    var dpResponse = workItem.dpResponse;
    logDebug("dpResponse.status: "+dpResponse.status);
    logDebug("dpResponse.activationCode: "+dpResponse.activationCode);
    logDebug("dpResponse.indexList: "+dpResponse.indexList);

    var responseObj = {
        STATUS: dpMapStatus(dpResponse.status),
        HOST_CODE: null,
        ACTIVATION_CODE: null,
        QA_INDEX_LIST: null
    };


    if (dpResponse.status == 0 ){
        if (dpResponse.hostCode != "" && dpResponse.hostCode != null){
            responseObj.HOST_CODE = dpResponse.hostCode;
        }
        if (dpResponse.activationCode != "" && dpResponse.activationCode != null){
            responseObj.ACTIVATION_CODE = dpResponse.activationCode;
        }
        if (dpResponse.indexList != "" && dpResponse.indexList != null) {
            responseObj.QA_INDEX_LIST = dpResponse.indexList;
        }
    } else {
        logError("The digipass adapter did not send a successfull response back");
        logError("StatusCode: "+dpResponse.status);
        logError("ErrorCode: "+dpResponse.rc);
    }

    //put the response object in the workItem for further use in the workflow
    workItem.responseObject = responseObj;
}

Articles in this section

Digipass Adapter [Deprecated]