table of contents
DACS_TOKEN(8) | DACS Web Services Manual | DACS_TOKEN(8) |
NAME¶
dacs_token - manage DACS one-time password token accountsSYNOPSIS¶
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.
•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.
OPTIONS¶
Web Service Arguments¶
In addition to the standard CGI arguments[8], dacs_token understands the following CGI arguments: CONFIRM_NEW_PINRequired 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:
MODE
•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.
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[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]AUTHOR¶
Distributed Systems Software ( www.dss.ca[12])COPYING¶
Copyright2003-2012 Distributed Systems Software. See the LICENSE[13] file that accompanies the distribution for licensing information.NOTES¶
- 1.
- dacsoptions
- 2.
- local_token_authenticate
- 3.
- dacstoken(1)
- 4.
- ADMIN_IDENTITY
- 5.
- TOKEN_REQUIRES_PIN
- 6.
- dacs.dss.ca
- 7.
- TOKEN_HOTP_ACCEPT_WINDOW
- 8.
- standard CGI arguments
- 9.
- dacs_admin
- 10.
- dacs.conf(5)
- 12.
- www.dss.ca
- 13.
- LICENSE
07/17/2013 | DACS 1.4.28b |