Section 3.64. <AuthBy SQLDIGIPASS>

3.64. <AuthBy SQLDIGIPASS>

Tip

<AuthBy
                           SQLDIGIPASS>

was previously called

<AuthBy
                           DIGIPASS>

. <AuthBy SQLDIGIPASS> is completely compatible with and replaces

<AuthBy
                           DIGIPASS>

. Although

<AuthBy
                           DIGIPASS>

is still a recognised name, it is officially deprecated, and support for it may be removed in the future. New installations are encouraged to use

<AuthBy
                           SQLDIGIPASS>

.

This module provides authentication of Vasco Digipass tokens from an SQL database. For more information, see Vasco website

. Digipass tokens are small hand-held devices that generate one-time passwords that change every minute. They can be purchased from Vasco and issued to your users. Such tokens provide much higher levels of security than static passwords. Additionally, with some types of token, users can set up individual PINs, which provides even higher levels of security with two-factor authentication. Some types of Digipass token can operate in a Challenge-Response mode. Vasco Digipass is supported by Radiator on Solaris, Linux, and Windows.

<AuthBy SQLDIGIPASS> supports all the common SQL configuration parameters. For more information about the SQL configuration parameters, see Section 3.8. SQL configuration.

<AuthBy
                     SQLDIGIPASS>

can be used to authenticate PAP, CHAP, MSCHAP, MSCHAPV2, EAP-MSCHAPV2, EAP-OTP, and EAP-GTC protocols.

<AuthBy SQLDIGIPASS> supports for Response Only (RO) and Challenge/Response (CR) tokens. It supports RADIUS PAP, TTLS-PAP, EAP-GTC, and EAP-OTP authentication methods. When using Challenge/Response tokens with PAP or TTLS-PAP, when the user enters an empty password, <AuthBy SQLDIGIPASS> generates the Challenge to enter into the Digipass token. The token then generates a Response which the users enters as their real password.

Radiator and

<AuthBy
                     SQLDIGIPASS>

can be configured in several ways including:

As a simple stand-alone system. A single SQL table contains information about each Digipass token and the user it is assigned to. You can use the digipass.pl program supplied with Authen::Digipass to import tokens, assign them to users and otherwise administer tokens and users. The example digipass.cfg Radiator configuration file shows a simple example of how to configure Radiator for such a system. Sample SQL database table definition files are provided with Radiator for a range of free and commercial SQL databases.
As an addition to a Radiator-compatible user-management system or ISP billing system. In this mode, Radiator is configured to authenticate using <AuthBy SQLDIGIPASS> from an SQL table, but also uses other information from the user-management system to save usage data, get user- or service-specific RADIUS reply items and so on.
In conjunction with Radiator Software's RAdmin RADIUS user management system. RAdmin provides an easy-to-install, easy-to-use web-based graphical system for managing RADIUS users for dial-up, wired and wireless authentication. RAdmin version 1.9 includes support for importing, allocating and administering Digipass tokens for authenticating users against Digipass instead of static passwords. RAdmin also works with any free or commercial SQL database. For more information about RAdmin, see RAdmin website .

<AuthBy SQLDIGIPASS> requires an additional Authen::Digipass module to be installed. The Authen::Digipass Perl module provides access to the Vasco Controller software that does the authentication of each token. Contact Radiator Software to obtain Authen::Digipass module for Solaris, Linux and Windows. See goodies/digipass-install.txt in your distribution for details on how to install and test Authen::Digipass for your platform.

<AuthBy SQLDIGIPASS> also requires an SQL database to hold information about each Digipass token that your system knows about. When you purchase a Digipass token from Vasco, you get also a DPX file that contains important data about the token. This DPX file must be imported into the

<AuthBy
                     SQLDIGIPASS>

database before the token can be authenticated by Radiator. You can use any free or commercial SQL database with <AuthBy SQLDIGIPASS>.

RAdmin provides all the tools you need for importing, allocating and administering Digipass tokens and users. In this case, use goodies/radminDigipass.cfg as an example Radiator configuration.

If you intend to use Digipass tokens with the example SQL database schema supplied in goodies/*.sql, use the digipass.pl program supplied and installed with Authen::Digipass for importing, allocating and administering Digipass tokens and users. In this case, use goodies/digipass.cfg as an example Radiator configuration.

Using Vasco Digipass tokens to generate passwords for AuthBy SQLDIGIPASS

Vasco produces a number of different types of token, some which require a PIN to be entered into the token, some which support user selected PINs, and some which do not support PINs. All tokens display a ‘tokencode’, usually in response to pressing a button on the face of the token. The different types of token are described below.

The simplest Digipass tokens include the Go-3, and which have an LCD display and a single button but no keypad. For these tokens, you press the button and use the tokencode displayed on the token as your password. Note that any attempt to use the same tokencode twice results a rejection. The error message on the Radiator log says ‘Code Replay Attempt’.

Go-1 and Go-3 tokens among others support user-selected static PINs, and also support the ability to change your PIN dynamically. Your initial PIN may have been selected by your administrator and given to you with your token. In any case, if you have a PIN, the password is made from the PIN followed by the tokencode displayed on the token. For example, if your PIN is 1234, and the token displays 89574526, then your password is ‘123489574526’. If you have not been assigned a PIN for your token, just use the tokencode displayed on the token as your password: ‘89574526’.

Go-1 and Go-3 tokens (among others) also support the ability to change your PIN. To change your PIN, you form the login password from your current PIN, followed by the tokencode, followed by the new PIN, followed by the new PIN again. For example, if your current PIN is 1234, and you wish to change the PIN to 9876, and the token is displaying 89574526, then you use the password 12348957452698769876. After this password has been accepted, your new PIN is active, and you must enter the new PIN at the beginning of each subsequent password.

Figure 2. Digipass Go-1 PIN passwords

After resetting the PIN (using either the digipass.pl application that comes with Authen::Digipass or the ‘Reset static password (PIN) for this token’ button in RAdmin), the token has no PIN associated with it. In that case, provide a new PIN with the next authentication attempt.

To do this enter the tokencode from the token followed by the new PIN twice. For example, if the current tokencode is 656565 and you want your new PIN to be 1234, enter 65656512341234 at your next authentication. For subsequent authentications, prefix the token code with your new PIN.

Some Digipass tokens have a keypad, which requires the token's PIN to be entered, and which also support Challenge-Response (CR). In Challenge-Response, when you first attempt to log in, Radiator sends a ‘Challenge’ (a sequence of digits) that you must enter into the token in order to generate the correct Response, which is then used as your password.

The first step is to attempt to log in with an empty password (i.e. a password with nothing in it). If the user's token supports CR, Radiator <AuthBy SQLDIGIPASS> sends a challenge of (typically) 4 digits:

Digipass Challenge: 8077

You use this challenge shortly. Now start the token by pressing the arrow button. The token asks for your PIN. Enter the 4 digit PIN (e.g. 1 - 2 - 3 - 4). The token will then display ‘APPL1’. Press ‘3’ to request Challenge-Response. The token displays ‘- - - -’. Enter the Digipass Challenge sent to you by Radiator (8077 in this example). The token displays a tokencode of 7 digits. Use the tokencode as your password.

Virtual Digipass

<AuthBy
                     DIGIPASS>

supports Virtual Digipass. Virtual Digipass tokens to do require an actual physical token. When the user attempts to log in, <AuthBy SQLDIGIPASS> generates the correct password and sends it to the user by a separate secure method such as SMS, voice etc. The user then enters the tokencode they receive from the separate channel, and <AuthBy SQLDIGIPASS> authenticates it just like a normal Digipass tokencode. Not all Vasco tokens support Virtual Digipass. This is determined by a flag in the token's DPX data file. In order to use Virtual Digipass, you need to purchase one or more Virtual Digipass token data files from Vasco. Real physical Digipass tokens can have DPX token files that also permit use of Virtual Digipass as a backup for the case where the token is lost or stolen.

Virtual Digipass allows Vasco token support even if the user does not have a physical token or has lost it. The SupportVirtualDigipass parameter makes <AuthBy SQLDIGIPASS> support Virtual Digipass tokens: If the incoming password is empty, and the token supports Virtual Digipass, <AuthBy SQLDIGIPASS> generates the user's correct tokencode and passes it to the VirtualTokencodeHook for delivery to the user by some secure out-of-band method such as SMS.

3.64.1. AuthSelect

This optional parameter specifies the SQL query that will be used to fetch Digipass data from the database. Special characters are permitted, and %0 is replaced with the quoted user name. Defaults to select DP_DATA, DIGIPASS from TBL_VASCODP where USER_ID=%0, which is compatible with the sample schemas provided in goodies/*.sql. The query is expected to return 2 fields in this order:

Digipass data block. This is 248 characters of encrypted data about the Digipass. It is encoded in printable characters.
Example: 10AFIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAGAAEAAAAgICAAAACx4 bwOmRYm8XYHErnjBAJIAWecbdhsRHIAAAAAAAAAAAAAAAAAAAAAA AAAAAAAAAAAAAAA+RmOzmh1lFwAAAYAAQAAAERQMzAwAAAAAAAAAAAAAACNOQpB57zTB/ XrAgg+7W/y
The Digipass serial number of 22 characters, including the token number and application name, and often some spaces, Example: '0097123456APPL 1 '. The spaces and application name are significant.

3.64.2. UpdateQuery

This optional parameter specifies the SQL query that will be used to store Digipass token data back to the database after authentication. The process of authentication (whether or not it is successful) results in the Digipass data block for that token being changed, and it must be written back to the database after each authentication attempt for correct operation. Special characters are permitted, and %0 is replaced with the new data block, and %1 is replaced with the Digipass serial number retrieved by AuthSelect.

Defaults to update TBL_VASCODP set DP_DATA=’%0’ where DIGIPASS=’% 1’, which is compatible with the sample schemas provided in goodies/*.sql.

3.64.3. ITimeWindow

This optional parameter specifies the size of the window of opportunity that a token can login with (this is counted in multiples of one-time password "rollovers" in the token. Value can be 2 to 1000. Default is 100 (that means +- 30 minutes for default tokens)

3.64.4. IThreshold

This optional parameter specifies the number of times that a person can unsuccessfully try to login before being locked out. 0 means disabled. Defaults to 0.

3.64.5. SyncWindow

This optional parameter specifies the size of the larger window that is created for use the first time after a token has been reset. This means that if a token gets out of sync (which is not an often occurrence), the user cannot log in so the administrator resets the token, then a larger sync window is produced after the reset so that the token can be recognised and calibrated by the software to allow subsequent use. This parameter is expressed in hours. Value can be 1 to 60. Default is 6 (hours).

3.64.6. CheckChallenge

This optional parameter specifies whether or not to check if the challenge has been corrupted before validation. Value can be 0 to 4:

0: No password checking
1: Check the parameter then verify (default)
2: Always use the DPData to validate responses
3: Avoid Challenge-Response Replay Attack by allowing only one challengeresponse authentication per timestep
4: Avoid Challenge-Response Replay Attack by rejecting the second response if responses from two consecutive authentication requests are equal and in the same time-step

3.64.7. ChkInactDays

This optional parameter specifies number of days of token inactivity. Past this number of days, the token will have to be reset. Values from 0 to 1024. Default is 0, which means the feature is disabled.

3.64.8. DeriveVector

This optional advanced parameter can be used to make data encryption unique for a host. Defaults to 0x00000000.

3.64.9. EventWindow

This optional advanced parameter specifies the Event Window size by number of iterations. Represents the acceptable event counter difference between Digipass token a and the host. It only applies to event-based operating modes. From 10 to 1000. Defaults to 100.

3.64.10. HSMSlotId

This optional advanced parameter specifies the HSM slot ID which will be used to store the Storage and Transport keys. 0 to 60. Defaults to 0.

3.64.11. StorageKeyId

This optional advanced parameter specifies the key which will be used to decrypt the Digipass data retrieved from the database. 0x00000000 to 0xffffffff. Defaults to 0x00000000.

3.64.12. TransportKeyId

This optional advanced parameter specifies the key which will be used to encrypt the Digipass data written to the database. 0x00000000 to 0xffffffff. Defaults to 0x00000000.

3.64.13. StorageDeriveKey1, StorageDeriveKey2, StorageDeriveKey3, StorageDeriveKey4

These optional advanced parameters specify the derivation keys used to make data encryption unique for a host.

3.64.14. ChallengeMessage

This parameter allows you to customise or internationalise the Reply-Message sent when the user is challenged to enter a Digipass tokencode. %0 is replaced with the digipass challenge string. Defaults to 'Digipass Challenge: %0'

# French challenge message:
ChallengeMessage Votre challenge du Digipass: %0

3.64.15. SupportVirtualDigipass

This optional parameter causes AuthBy SQLDIGIPASS to support Vasco Virtual Digipass tokens.

3.64.16. VirtualTokencodeHook

If the SupportVirtualDigipass flag is enabled, this parameter specifies Perl code that is called whenever a Virtual Digipass tokencode is to be sent to a user. The hook is expected to transmit the tokencode to the user over some prompt, secure out-of-band method, such as SMS. The VirtualTokencodeHook is called like:

VirtualTokencodeHook($self, $username, $tokencode, $p)

VirtualTokencodeHook must return an error message if it fails to start delivery of the tokencode the user, otherwise it must return undef.

3.64.17. ChallengeTimeout

This optional parameter sets the maximum period of time that a challenge from a Challenge-Response (CR) token will be valid for. Time is in seconds and defaults to 300 seconds (5 minutes).