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; }
Comments
Please sign in to leave a comment.