Digipass DB adapter
The Digipass DB Adapter allows TrustBuilder to use strong authentication using a Digipass token. This token can be a hardware token or a software token.
The Digipass DB adapter uses a specific database schema. A schema for MySQL and Oracle are available.
The Digipass DB adapter will try to authenticate a user and manage the tokens assigned to a user. Two scenarios are possible:
You store the user information in the database.
You have a user repository (identity store) and will use that repository to store your user data.
In case of scenario 1, you will need the PERSON table (see below). In case of scenario 2 (the default) the PERSON table should not exist. Inserting data and updating data in the PERSON table is not part of the Digipass DB adapter.
Database Schema
All the token information will be stored in a database. The structure of this database is explained in this section and is part of a generic authentication model. The database has the following tables for Digipass:
PERSON (optional)
AUTH_PRINCIPAL
TOKEN
Table PERONS has the following columns:
ID: The primary key
USERID
FIRSTNAME
LASTNAME
... (depending on the data you want to store about a user in the database)
Table AUTH_PRINCIPAL has the following columns:
PRINCIPAL: if a customer already has an identity store, the type will be a VARCHAR. If the customer does not have an identity store, the type will be an INT referencing to the PERSON(ID) column.
AUTH_ID: references to the TOKEN(ID) column. However, no foreign key constraint will be made to the TOKEN table because AUTH_ID will hold a reference to multiple tables. If Digipass is the only authentication mechanism, then a foreign key constraint can be made between this column and the AUTH_ID column.
AUTH_TYPE: Will contain the table name where the authentication information is found for this user. For Digipass, this will contain the value ‘TOKEN’.
LOGINID: The id used to login to the application.
LOGIN_POLICY: A reference to the login policy that should be used. We do not supply means of checking the LOGIN_POLICY. This should be handled separately.
STATUS: Will contain the status of this authentication row. At the moment, we have 2 statuses: enabled and disabled.
Table TOKEN has the following columns:
ID: The primary key of the table
SERIALNR: Will contain the Digipass token serial number.
DPBLOB: Will contain a base64 encoded string containing the Digipass token blob.
APPLICATION: Will contain the application to which this Digipass token blob applies.
DPMODE: Will contain the Digipass token blob mode.
DPTYPE: Will contain the Digipass token type.
QABLOB: Will contain the Questions and Answers blob.
STATUS: Will contain the status of the token.
Configuration
The DigipassDB adapter allows you to configure the following:
The JDBC Adapter that will be used to connect to the external database. This parameter is required.
The Vacman controller kernel parameters. For more information on the kernel parameters: see the “VACMAN Controller Product Guide”. The default values are recommended in most situations.
Request - API (Administration)
Import DPX
This is not part of the Digipass DB adapter but is required to import tokens into the database. The class that imports tokens from a DPX file can be found in the TrustBuilder config jar: be.securit.trustbuilder.tools.DigipassDbDpxLoader.
This class takes one argument: the path to a properties file. The properties file has the following keys:
type: token
dpxfile: The (absolute) path to the DPX file you want to import
key: The key of the DPX file
db.driver: The database driver
db.url: The database URL
db.password: The database password
applmapping1>: These optional fields allow you to map an application in the DPX file to an application in the database. If for instance you specify: “applmapping1=APPL 1, banking”, all the tokens of APPL 1 in the DPX will be stored with application “banking” in the database. The index starts at 1, is ascending and no gaps are allowed. If not specified, the applications are stored as the application specified in the DPX file.
appltoimport: A comma separated list of applications in the DPX file you want to import. If not specified, all applications are imported.
activationcodefile: The path to the file where the activation codes of the tokens are stored. This file is supplied with the DPX file.
The Digipass Kernel parameters can also be specified. See 'VACMAN Controller Product Guide' for more information. Possible properties:
IdentificationTimeWindow
SignatureTimeWindow
GMTAdjustment
CheckChallenge
IdentificationThreshold
SignatureThreshold
CheckInactiveDays
DeriveVector
SynchronizationWindow
OnlineSignature
EventWindow
HSMSlotId
StorageKeyId
TransportKeyId
StorageDeriveKeys0
StorageDeriveKeys1
StorageDeriveKeys2
StorageDeriveKeys3
Take great care when specifying the Digipass Kernel parameters. Under most circumstances, you should not alter the default values.
Link Token Request (digipassDBLinkTokenRequest)
This request will allow you to link a user to a token.
Application (String): required.
Serial number (String): required.
Loginid (String): required.
Principal (String): required.
Login Policy (String): optional.
Token (Boolean): optional. Defaults to true (single token)
User (Boolean): optional. Defaults to true (single user)
Unlink token request (digipassDBUnlinkTokenRequest)
This request will unlink a user from a token.
Serialnr (String): Optional.
Application (String): Required.
Loginid (String): Required.
Principal (String): Optional. Required if a token can be linked to multiple users.
Unlock token request (digipassDBUnlockTokenRequest)
This request will unlock a tyoken from a user for a specific application.
Application (String): required
Serialnr (String): optional
Principal (String): optional
Loginid (String): required
Randomnr (String): required.
Change static password request (digipassDBChangeStaticPasswordRequest)
This request will change the static password of a token.
Application (String): required.
Loginid (String): optional.
Serialnr (String): required.
Principal (String): optional.
Pwd1 (String): required.
Pwd2 (String): required.
Delete Token request (digipassDBDeleteTokenRequest)
This request will delete a token.
Application (String): required.
Serialnr (String): required.
Free Token Request (digipassDBFindFreeTokenRequest)
Find the first token with status 0 (free).
Application (String): required.
Type (String): optional.
Find Tokens Request (digipassDBFindTokensRequest)
Find the tokens attached to the principal.
Principal (String): The principal you want the tokens for.
Find Users Request (digipassDBFindUsersRequest)
Find the principals linked to a token.
Serialnr (String): required.
Force Pin Change Request (digipassDBForcePinChangeRequest)
Trigger a force pin change.
Application (String): required.
Serialnr (String): required.
Reset Static Password (digipassDBResetStaticPasswordRequest)
Resets Digipass Static PIN.
Application (String): required.
Serialnr (String): required.
Reset Token Request (digipassDBResetTokenRequest)
Resets a Digipass token.
Application (String): required.
Serialnr (String): required.
DB Sync Token Request (digipassDBSyncTokenRequest)
Synchronize a Digipass token.
Application (String): required.
Serialnr (String): required.
Pwd1 (String): required.
Chl1 (String): required.
Pwd2 (String): required.
Chl2 (String): required.
Token Info Request (digipassDBTokenInfoRequest)
Retrieve the Digipass token info.
Application (String): required.
Serialnr (String): required.
Request - API (Authentication)
General Remark
All authentication requests will use the following parameters:
Loginid (String): required.
Application (String): required.
Serial number (String): optional.
Principal (String): optional.
Application and login id are required as they are the minimum information you need to login to an application. The serial number is optional if only one token can be assigned to one user (single user). In that case, the serial number will be retrieved using login id and application. An error will be generated if more than one token is found. Principal is also optional but only if a user can be linked to one token (single token). Otherwise we have no means of finding which user is trying to generate the challenge. An error will be generated if the principal was not found.
Generate Challenge Request (digipassDBGenerateChallengeRequest)
This request will generate a challenge for challenge response authentication.
Loginid (String): required.
Application (String): required.
Serial number (String): optional.
Principal (String): optional.
Authenticate Token (digipassDBAuthenticateTokenRequest)
Will perform challenge/response or response authentication.
Loginid (String): required.
Application (String): required.
Password (String): required.
Challenge (String): optional but required for challenge/response authentication (see Generate Challenge Request)
Serialnr (String): optional.
Principal (String): optional.
Verify Signature (digipassDBVerifySignatureRequest)
Will perform a signature verification.
Signature (String): Required.
SignedFields (String array): Required.
Loginid (String): Required.
Application (String): Required.
Serialnr (String): Optional.
Principal (String): Optional.
Response - API
Common Properties
All responses have three 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
message Response specific message in case there was a problem (can be null)
Some requests return more than these three common properties and are listed below.