Digipass Service

Digipass Service

Requirements

To use this service you must first install the VACMAN Controller. Then you need to do the following steps:

  • Add the aal2wrap.jar to your classpath. The file can be found in your VACMAN controller installation directory.
  • Add the VACMAN controller library to your classpath or to your java.library.path. The file can be found in your VACMAN controller installation directory. Make sure the version matches your platform.
  • Create a MySQL database scheme and populate it using the digipassservicemysql.sql script. It can be found in the trustbuilder.war.

Property

Database Properties

Property Description
jdbcUrl The JDBC Url you want to use to connect to the database.
username The username to use to connect to the database.
password The username password to connect to the database.

Digipass Properties

Property Default Description
CheckChallenge 1 0: No challenge checking
1: Check 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
DeriveVector 0 Vector used to make the data encryption unique for a host
DiagnosticLevel 0 Requested diagnostic level
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
SignatureTimeWindow 24 Signature window size in number of time steps.
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 8388607 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.

Invoking Digipass Service in the scripts

The Digipass service is used to load the Digipass tokens into the database and use them to do validation.

Retrieving the service :

var digipassService = tb.getService("DigipassService");

Functions

loadDPX(filename, transportkey, staticvector)

Loads the DPX file specified in the filename parameter and stores it into the database. The transportkey is the key used to decrypt the DPX file. If the staticvector parameter is not specified, the call will try to retieve it from the DPX file. If you specify the staticvector parameter, it should be the unencrypted staticvector.

digipassService.loadDPX("/opt/securit/dpx/demo.dpx", "11111111111111111111111111111111", null);

This method can throw SQLExceptions and DigipassExceptions which should be handled by the caller.

generateActivationCode(serialnumber)

This method activates the Digipass token and returns a digipass activation object. This digipass activation object contains 3 fields that can be retrieved: * Serial number with getSerialNumber(). * Activation code with getActivationCode(). * Encrypted event reactivation counter with getXerc().

var data = digipassService.generateActivationCode("VDS10000120");

This method can throw SQLExceptions and DigipassExceptions which should be handled by the caller.

validateOtp(serial, application, otp)

Validates the One Time Password (OTP) for that serial number and application. If the Digipass serial only has one Response Only application, then application should not be supplied in the parameters. Otherwise it is required.

digipassService.validateOtp("VDS10000120", null, "123456");

This method can throw SQLExceptions, DigipassExceptions and IllegalArgumentException which should be handled by the caller.

getFreeDigipass(dpType)

This method returns the serial number of the first available Digipass of that type or the first free Digipass that is available (if dpType is not specified). There are 5 different values for status.

  • Free (0)
  • Pending (1)
  • Assigned (2)
  • Revoked (99)
  • Unavailable (-1)

Depending on the situation you may update the status from Free to Pending or from Free to Assigned.

digipassService.getFreeDigipass("DP300");

This method can throw SQLExceptions which should be handled by the caller.


getFreeLicense()

This method returns the serial number of the first available MDL Digipass license. We have 5 possible  status values:

  • Free (0)
  • Pending (1)
  • Assigned (2)
  • Revoked (99)
  • Unavailable (-1)


digipassService.getFreeLicense();

This method can throw SQLExceptions which should be handled by the caller.

updateDigipassStatus(serialnumber, status, application)

Updates the status of the Digipass serial to the specified status. We have 3 statusses:

  • Free (0)
  • Pending (1)
  • Assigned (2)
  • Revoked (99)
  • Unavailable (-1)

If the application is specified, only that application status is updated. In general you will want to update all the statusses of the Digipass applications to a certain value.

digipassService.getFreeDigipass("VDS10000120", 2, null);

This method can throw SQLExceptions and IllegalArgumentException which should be handled by the caller.

updateLicenseStatus(serialnumber, status)

Updates the status of a specific Digipass  MDL license to the specified status. We have 5 status values:

  • Free (0)
  • Pending (1)
  • Assigned (2)
  • Revoked (99)
  • Unavailable (-1)


digipassService.updateLicenseStatus("VDS10000120", 2);

This method can throw SQLExceptions and IllegalArgumentException which should be handled by the caller.

updateInstanceStatus(serialnumber, instanceNumber, status)

Updates the status of a specific instance for a specific Digipass  MDL license to the specified status. We have 5 status values:

  • Free (0)
  • Pending (1)
  • Assigned (2)
  • Revoked (99)
  • Unavailable (-1)


digipassService.updateInstanceStatus("VDS10000120",1,2);

This method can throw SQLExceptions and IllegalArgumentException which should be handled by the caller.


getDigipassStatus(serialnumber, application)

Returns the status of the Digipass as an integer based on the serial number and the application (optional). If the application is not supplied, all the applications should have the same status or -1 will be returned.

var status = digipassService.getDigipassStatus("VDS10000120");

getDigipassByDpType(dpType, status)

Returns an array of DigipassToken objects for a specific type and status

digipassService.getDigipassByDpType("DP300",0);

Returns an array of objects

[{"serialNumber":"VDS10000120",
  "dpMode":"CR", //possible values are CR, RO, SG and MM
  "dpBlob":"12f1ds231f23ds, //base64 encoded string of the blob
  "dpType":"DP300",
  "application":"APPL1",
  "sharedSecret":"1346", //aka Pin
  "staticVector":"456f4ds54fd65s",
  "statusChanged":1525770790000,
  "status":"FREE",
  "blobCounter":2
}]

getDigipassTypes()

Returns an array of strings of digipass types available in the database.

digipassService.getDigipassTypes();

Returns an array of strings

["DP300","DP700","DPMOB"]

resetTokenBlobs(serialnumber)

This method resets all the Digipass application blobs.

digipassService.resetTokenBlobs("VDS10000120");

changeStaticPassword(serialnumber, pwd1, pwd2)

This methods allows you to reset the static/server PIN from a Digipass token. The Digipass token will need to support the server PIN functionality (for example the Digipass GO 1). Generated OTPs will need to be prepended with this server PIN. The parameters pwd1 and pwd2 will need to be identical in order to successfully change the server PIN.

resetStaticPassword(serialnumber)

This function is used in combination with a DIGIPASS that can use a static PIN (e.g. DIGIPASS GO 1). The user will have to define his static PIN at the next authentication request. In order to activate this option, the PIN Change Allowed functionality has to be activated.

digipassService.resetStaticPassword("VDS10000120");

mdlGenerateLicenseActivationMsg(serialnumber, crontosize, crontoonpaper)

Generates the first activation message in the process of activation of a multi-device license


digipassService.mdlGenerateLicenseActivationMsg("VDS10000120",400,false);

The returning object is as below. 

{"serialNumber":"VDS10000120",
 "cronto":"base64StringOfCrontoImageInPNGformat",
 "challenge":"challengeString"
}

The cronto image can be rendered using an HTML <img tag with the SRC using base 64.

<img src="data:image/png;base64,iVBORw0KG....."/>

mdlGenerateInstanceActivationMsg(serialnumber, challenge, devicecode, crontosize, crontoonpaper)

Generates the second activation message in the process of a multi device license.  The cronto size argument defines the size of the cronto image, in pixels, that is to be created


digipassService.mdlGenerateInstanceActivationMsg("VDS10000120","theChallenge","deviceID", 400, false);

The returning object is as below. 

{"serialNumber":"VDS10000120",
 "cronto":"base64StringOfCrontoImageInPNGformat",
 "signedMessage":"signedMessageString",
 "instanceNumber":"12346"
}

The cronto image can be rendered using an HTML <img tag with the SRC using base 64.

<img src="data:image/png;base64,iVBORw0KG....."/>

mdlGenAuthRequest(serialnumber, DigipassMdlSignOptions)

Generates an authentication request which can be used to authenticate an end user when multi-device license is installed.  The serialnumber argument is the serial number of an instance token to generate the authentication request for. The options can be null to use the default signing options or an object.

digipassService.mdlGenAuthRequest("VDS10000120",null);

This is an example of the options object:

{"crontoSize":10,
 "crontoOnPaper":false,
 "crontoOnHw":false,
 "msgBase64":true,
 "spacesAsTabs:2,
 "spacesString":null,
 "title":null,
 "vascoAskApproval":true,
 "vascoAskPin":true,
 "vascoShowData":true,
 "vascoShowMac":true,
 "vascoShowWarning":true}

The returning object is as below. 

{"serialNumber":"VDS10000120",
 "cronto":"base64StringOfCrontoImageInPNGformat",
 "signedMessage":"signedMessageString"
}

The cronto image can be rendered using an HTML <img tag with the SRC using base 64.

<img src="data:image/png;base64,iVBORw0KG....."/>


mdlGenFTRequest(serialnumber, freetext, options)

Generates a free text request which can be used to authenticate an end user when using a multi-device license.

digipassService.mdlGenFTRequest("VDS10000120","freeTextString",{options});

This is an example of the options object:

{"crontoSize":10,
 "crontoOnPaper":false,
 "crontoOnHw":false,
 "msgBase64":true,
 "spacesAsTabs:2,
 "spacesString":null,
 "title":null,
 "vascoAskApproval":true,
 "vascoAskPin":true,
 "vascoShowData":true,
 "vascoShowMac":true,
 "vascoShowWarning":false}

The returning object is as below. 

{"serialNumber":"VDS10000120",
 "cronto":"base64StringOfCrontoImageInPNGformat",
 "signedMessage":"signedMessageString"
}

The cronto image can be rendered using an HTML <img tag with the SRC using base 64.

<img src="data:image/png;base64,iVBORw0KG....."/>


mdlGenSignRequest(serialnumber,  [{"key":"value"}], {options})

Generates a signing request which can be used to authorize a transaction of the end user

digipassService.mdlGenSignRequest("VDS10000120",[{"key":"value"}, {"key2","value2"}],{options});

This is an example of the options object:

{"crontoSize":10,
 "crontoOnPaper":false,
 "crontoOnHw":false,
 "msgBase64":true,
 "spacesAsTabs:2,
 "spacesString":null,
 "title":null,
 "vascoAskApproval":true,
 "vascoAskPin":true,
 "vascoShowData":true,
 "vascoShowMac":true,
 "vascoShowWarning":false}

The returning object is as below. 

{"serialNumber":"VDS10000120",
 "cronto":"base64StringOfCrontoImageInPNGformat",
 "signedMessage":"signedMessageString"
}

The cronto image can be rendered using an HTML <img tag with the SRC using base 64.

<img src="data:image/png;base64,iVBORw0KG....."/>


mdlValidateInstanceActivationMsg(serialnumber, sequencenumber, message, signature, expirationtimeSeconds)

Validates the response to the instance activation message

digipassService.mdlValidateInstanceActivationMsg("VDS10000120","1234","generatedActivationMessage","signatureToValidateString",120);

The returning object is as below. 

{"instanceToken":
   {"serialNumber":"VDS10000120",
    "instanceNumber":"12345",
    "applicationName":"APPL1",
    "deviceId":"458f7ds895fe4w4f8edw5f4af",
    "deviceType":"DP110" 
   },
 "statusCode":"203"
}


mdlValidateSignature(serialnumber, signedmessage, signature, expirationtime)

Validates a supplied signature to a signed message which was generated by mdlGenAuthRequest() mdlGenSignRequest()

digipassService.mdlValidateSignature("VDS10000120","originalSignedMessage","signatureToCheck",120);

The returning object is as below. 

{"instanceToken":
   {"serialNumber":"VDS10000120",
    "instanceNumber":"12345",
    "applicationName":"APPL1",
    "deviceId":"458f7ds895fe4w4f8edw5f4af",
    "deviceType":"DP110" 
   },
 "statusCode":"203"
}


generateActivationCode(serialnumber)

Generates an activation code for use with single lincense tokens. The response returns an XFAD for online activation.


digipassService.generateActivationCode("VDS10000120");

The returning object is as below. 

{"serialNumber":"VDS10000120",
 "activationCode":"45fds4f94dsa65",
 "xerc":"456f4dsa56f4ds"
}


blockLicenseInstances(serialnumber, block)

Blocks a Digipass MDL licences. If block is true then the status is set to revoked. If block is false then status is set to assigned.

digipassService.blockLicenseInstances("VDS10000120",true);

blockSingleLicenseInstance(serialnumber, instanceNumber, block)

Blocks a single instance of a Digipass MDL licence. If block is true then the status is set to revoked. If block is false then status is set to assigned.

digipassService.blockSingleLicenseInstance("VDS10000120",1,true);

blockTokenApp(serialnumber, app, block)

Blocks a single application of a single token. If block is true then the status is set to revoked. If block is false then status is set to assigned.

digipassService.blockTokenApp("VDS10000120","APPL1",true);

getLicense(serialnumber)

Get a single license by it's serial number. Returns a DigipassLicense object

digipassService.getLicense("VDS10000120");
{serialNumber:"VDS10000120",
 "activationType":"online",
  "masterAppName":"ACTIV APP",
  "masterAppAMode":"MA",
  "masterAppBlob":"456f4dsa56f4ds",
  "activationVector":"456f4d5sf4d5s6ds",
  "payloadKeyBlob":"56f4dsa56f4d6",
  "status":PENDING,
  "messageVector":"1",
  "staticVector:"1",
  "tokens":[arrayOfTokenObjectsBeingActivatedInstances]
}

getInstance(serialnumber, instanceNumber)

Get a single token instance for a specific MDL license by the serial number of the license and the instance number of the token instance. Returns a DigipassToken object

digipassService.getInstance("VDS10000120",1);
{"serialNumber":"VDS10000120",
  "dpMode":"CR", //possible values are CR, RO, SG and MM
  "dpBlob":"12f1ds231f23ds, //base64 encoded string of the blob
  "dpType":"DP300",
  "application":"APPL1",
  "sharedSecret":"1346", //aka Pin
  "staticVector":"456f4ds54fd65s",
  "statusChanged":1525770790000,
  "status":"ASSIGNED",
  "blobCounter":2,
  "instanceNumber":1
}
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

0 comments

Please sign in to leave a comment.