dacs_token - manage DACS one-time password token accounts
This program is part of the DACS
web service provides limited account management operations
on accounts recognized by local_token_authenticate
, a DACS
authentication module. Full administrative functionality is provided by
; 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
•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
•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
 using the item types auth_token, auth_hotp_token, and
The same account security stipulations as dacstoken
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.
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
•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.
In addition to the standard CGI arguments
understands the following CGI arguments:
Required with the SET_PIN operation, the value
of this argument must be the same as the value of
The following operations are supported:
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
. 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
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 or change the PIN associated with the account for USERNAME
operation requires the NEW_PIN
Synchronize the account for USERNAME
so that the next password produced
by the token is expected to be valid. This operation requires the
, and USERNAME
Create a demonstration account according to the given arguments, configuration
values, and defaults. Required arguments: MODE
. Optional arguments: NEW_PIN
HOTP argument: COUNTER
. Optional TOTP arguments: DIGEST_NAME
. The KEY_ENCODING
argument, which indicates how the
string has been encoded, must be one of hex, base32, or none.
Synchronize a demonstration account using USERNAME
, a one-time password
or password sequence ( SYNC
), and optional PIN
Validate the given demonstration account ( USERNAME
), one-time 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
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
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
 for everything else. Full-blown web-based token account
management should either be provided by dacs_token
Demonstration mode accounts should be manually deleted from time to time.
is not understood. XML responses should be implemented.
. Also see the OTP token demonstration,
Distributed Systems Software ( www.dss.ca
Copyright2003-2015 Distributed Systems Software. See the LICENSE
that accompanies the distribution for licensing information.
- standard CGI arguments