Provided by: dacs_1.4.38a-2build1_amd64 bug

NAME

       dacs_token - manage DACS one-time password token accounts

SYNOPSIS

       dacs_token [dacsoptions[1]]

DESCRIPTION

       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 passwords.

       Subject to configuration and valid authorization, this web service lets:

       •   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.

           Security
           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 token's.

OPTIONS

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

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

       OPERATION
           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 parameters;

                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, KEY_ENCODING. Optional
               arguments: NEW_PIN, CONFIRM_NEW_PIN, NDIGITS, BASE, SERIAL. Optional HOTP
               argument: COUNTER. Optional TOTP arguments: DIGEST_NAME, TIME_STEP. The
               KEY_ENCODING argument, which indicates how the KEY string has been encoded, must
               be one of hex, base32, or none.

           •   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.

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

       NEW_PIN
           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.

       PASSWORD
           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.

       PIN

       USERNAME
           The DACS username of interest.

DIAGNOSTICS

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

BUGS

       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 dacs_admin(8)[9].

       Demonstration mode accounts should be manually deleted from time to time.

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

SEE ALSO

       dacstoken(1)[3], dacs.conf(5)[10], dacs_authenticate(8)[11]. Also see the OTP token
       demonstration, token_demo.html.

AUTHOR

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

COPYING

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

NOTES

        1. dacsoptions
           http://dacs.dss.ca/man/dacs.1.html#dacsoptions

        2. local_token_authenticate
           http://dacs.dss.ca/man/dacs_authenticate.8.html#local_token_authenticate

        3. dacstoken(1)
           http://dacs.dss.ca/man/dacstoken.1.html

        4. ADMIN_IDENTITY
           http://dacs.dss.ca/man/dacs.conf.5.html#ADMIN_IDENTITY

        5. TOKEN_REQUIRES_PIN
           http://dacs.dss.ca/man/dacs.conf.5.html#TOKEN_REQUIRES_PIN

        6. dacs.dss.ca
           http://dacs.dss.ca

        7. TOKEN_HOTP_ACCEPT_WINDOW
           http://dacs.dss.ca/man/dacs.conf.5.html#TOKEN_HOTP_ACCEPT_WINDOW

        8. standard CGI arguments
           http://dacs.dss.ca/man/dacs.services.8.html#standard_cgi_args

        9. dacs_admin(8)
           http://dacs.dss.ca/man/dacs_admin.8.html

       10. dacs.conf(5)
           http://dacs.dss.ca/man/dacs.conf.5.html

       11. dacs_authenticate(8)
           http://dacs.dss.ca/man/dacs_authenticate.8.html

       12. www.dss.ca
           http://www.dss.ca

       13. LICENSE
           http://dacs.dss.ca/man/../misc/LICENSE