man dacs_token (8): manage DACS one-time password token accounts

SYNOPSIS

dacs_token [m[blue]dacsoptionsm[][1]]

DESCRIPTION

This program is part of the DACS suite.

The dacs_token web service provides limited account management operations on accounts recognized by m[blue]local_token_authenticatem[][2], a DACS authentication module. Full administrative functionality is provided by dacstoken; refer to m[blue]dacstoken(1)m[][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 m[blue]ADMIN_IDENTITYm[][4]) set, change, or remove the PIN on any account, synchronize an account with a token (removal depends on m[blue]TOKEN_REQUIRES_PINm[][5]), or obtain the next OTP for a specified account;

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

Outside of demonstration mode operation, accounts are managed identically to m[blue]dacstoken(1)m[][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 m[blue]TOKEN_REQUIRES_PINm[][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 m[blue]TOKEN_HOTP_ACCEPT_WINDOWm[][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 m[blue]standard CGI argumentsm[][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. 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.

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 m[blue]TOKEN_REQUIRES_PINm[][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 m[blue]dacstoken(1)m[][3] for everything else. Full-blown web-based token account management should either be provided by dacs_token or m[blue]dacs_adminm[][9].

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

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