DACS_TOKEN(8)              DACS Web Services Manual              DACS_TOKEN(8)

       dacs_token - manage DACS one-time password token accounts

       dacs_token [dacsoptions[1]]

       This program is part of the DACS suite.

       The dacs_token web service provides limited account management
       operations on accounts recognized by local_token_authenticate[2], a
       DACS authentication module. Full administrative functionality is
       provided by dacstoken; refer to dacstoken(1)[3] for detailed
       information about one-time passwords, token devices, and user accounts.
       These accounts are completely separate from any other accounts and

       Subject to configuration and valid authorization, this web service

       •   users set an initial PIN for their account (note that his presents
           a window of opportunity for an attacker that has obtained a
           PIN-less token);

       •   users change the PIN on their account;

       •   users synchronize their account with their token; and

       •   DACS administrators (see ADMIN_IDENTITY[4]) set, change, or remove
           the PIN on any account, synchronize an account with a token
           (removal depends on TOKEN_REQUIRES_PIN[5]), or obtain the next OTP
           for a specified account;

       •   anyone create and test a demonstration account (visit
           dacs.dss.ca[6] to try a live demonstration).

       Outside of demonstration mode operation, accounts are managed
       identically to dacstoken(1)[3] using the item types auth_token,
       auth_hotp_token, and auth_totp_token.

           The same account security stipulations as dacstoken apply.

           The web service applies access controls internally; a DACS ACL can
           be added to further restrict its use. The internal rules are:

           •   A DACS administrator can synchronize any account without
               providing the account's PIN; other users must provide the
               account's PIN, if there is one.

           •   A DACS administrator can set, change, or remove (depending on
               TOKEN_REQUIRES_PIN[5]) any account's PIN; other users can set
               or change their account's PIN by:

               •   authenticating as the username of the account being
                   accessed (if the account has a PIN and the user has
                   forgotten it, presumably a different authentication method
                   must be used); or

               •   contacting a DACS administrator.

           •   Demonstration mode is enabled if the item type auth_token_demo
               is defined; otherwise, if auth_token_hotp_demo is defined, then
               demonstration mode for HOTP is enabled, and if
               auth_token_totp_demo is defined, then demonstration mode for
               TOTP is enabled. If none of these item types is enabled, which
               is the default, then demonstration mode is inoperative.

       When validating a HOTP one-time password, the
       TOKEN_HOTP_ACCEPT_WINDOW[7] configuration directive can be used to
       allow an account's counter value to automatically "catch up" to the

   Web Service Arguments
       In addition to the standard CGI arguments[8], dacs_token understands
       the following CGI arguments:

           Required with the SET_PIN operation, the value of this argument
           must be the same as the value of CONFIRM_NEW_PIN.

           The following operations are supported:

           •   CURRENT

               Unlike the other operations, this operation returns a
               text/plain MIME type, consisting of the current moving factor
               (i.e., the HOTP counter value or the TOTP interval value),
               followed by a space and the corresponding OTP for USERNAME.
               This facilitates an easy-to-use, REST-type interface. In the
               case of HOTP, the counter value is advanced, "consuming" the
               OTP. Only an administrator is allowed to perform this
               operation, which can be used to build a simple mutual
               authentication capability:

                1. The user gives a username to the sign-on procedure;

                2. The sign-on procedure asks DACS for the OTP it expects the
                   user's token to produce, based on the user's account

                3. The sign-on procedure presents the OTP to the user, who
                   verifies its correctness by matching the presented OTP with
                   the one actually produced by the token;

                4. The user continues the authentication procedure, perhaps by
                   providing the token's next OTP or using another
                   authentication method, such as a password.

               The appropriateness of TOTP mode for mutual authentication
               depends on the OTP lifetime and other configuration parameters.

           •   SET_PIN

               Set or change the PIN associated with the account for USERNAME.
               This operation requires the NEW_PIN, CONFIRM_NEW_PIN, MODE, and
               USERNAME arguments.

           •   SYNC

               Synchronize the account for USERNAME so that the next password
               produced by the token is expected to be valid. This operation
               requires the PASSWORD, MODE, and USERNAME arguments.

           •   DEMO_CREATE

               Create a demonstration account according to the given
               arguments, configuration values, and defaults. Required
               arguments: MODE, KEY. Optional arguments: NEW_PIN,
               CONFIRM_NEW_PIN, NDIGITS, BASE, SERIAL. Optional HOTP argument:
               COUNTER. Optional TOTP arguments: DIGEST_NAME, TIME_STEP.

           •   DEMO_SYNC

               Synchronize a demonstration account using USERNAME, a one-time
               password or password sequence (SYNC), and optional PIN.

           •   DEMO_VALIDATE

               Validate the given demonstration account (USERNAME), one-time
               password (PASSWORD), and PIN (PIN) in demonstration mode. No
               credentials are actually issued.

           This argument is the device mode, which may be (case insensitively)
           counter or hotp for counter mode, or time or totp for time-based

           With the SET_PIN operation, this is the new PIN to associate with
           the account. An administrator can remove the PIN entirely, provided
           it is allowed by TOKEN_REQUIRES_PIN[5], by omitting (or not
           providing a value for) both NEW_PIN and CONFIRM_NEW_PIN.

           If the request is not accompanied by credentials for USERNAME or an
           administrator identity, this one-time password must validate
           against the expected value for USERNAME.


           The DACS username of interest.

       The program exits 0 if everything was fine, 1 if an error occurred.

       This version only provides self-service operations for users and
       limited account management for a DACS administrator; administrators
       must use dacstoken(1)[3] for everything else. Full-blown web-based
       token account management should either be provided by dacs_token or

       Demonstration mode accounts should be manually deleted from time to

       The FORMAT is not understood. XML responses should be implemented.

       dacstoken(1)[3], dacs.conf(5)[10], dacs_authenticate(8)[11]

       Distributed Systems Software (www.dss.ca[12])

       Copyright2003-2012 Distributed Systems Software. See the LICENSE[13]
       file that accompanies the distribution for licensing information.

        1. dacsoptions

        2. local_token_authenticate

        3. dacstoken(1)



        6. dacs.dss.ca


        8. standard CGI arguments

        9. dacs_admin

       10. dacs.conf(5)

       11. dacs_authenticate(8)

       12. www.dss.ca

       13. LICENSE

DACS 1.4.28b                      02/04/2014                     DACS_TOKEN(8)