DACS_TOKEN(8) | DACS Web Services and CGI | DACS_TOKEN(8)

## NAME

dacs_token — manage DACS one-time password token accounts

## SYNOPSIS

`dacs_token` [`dacsoptions`]

## 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, a DACS authentication module. Full administrative functionality is provided by dacstoken; refer to dacstoken(1) 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) set, change, or remove the PIN on any account, synchronize an account with a token (removal depends on TOKEN_REQUIRES_PIN), or obtain the next OTP for a specified account;

- anyone create and test a demonstration account (visit dacs.dss.ca to try a live demonstration).

Outside of demonstration mode operation, accounts are managed identically to dacstoken(1) 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) 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 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, 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, 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) for everything else. Full-blown web-based token account management should either be provided by dacs_token or dacs_admin(8).

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), dacs.conf(5), dacs_authenticate(8). Also see the OTP token demonstration, `token_demo.html`.

## AUTHOR

Distributed Systems Software (www.dss.ca)

## COPYING

Copyright © 2003-2015 Distributed Systems Software. See the `LICENSE` file that accompanies the distribution for licensing information.

DACS Version 1.4.38a | 23-Nov-2016 | DACS_TOKEN(8)

Table of Contents

Font:

- Z
- Z
- Z
- Z

−−

Set

++

$Id: dacs_token.8.xml 2868 2015-12-28 22:38:59Z brachman $