.\" Copyright (c) 2003-2012
.\" Distributed Systems Software.  All rights reserved.
.\" See the file LICENSE for redistribution information.
.\" $Id: copyright-nr 2564 2012-03-02 00:17:08Z brachman $
'\" t
.\"     Title: dacs_token
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 02/19/2019
.\"    Manual: DACS Web Services Manual
.\"    Source: DACS 1.4.40
.\"  Language: English
.\"
.TH "DACS_TOKEN" "8" "02/19/2019" "DACS 1.4.40" "DACS Web Services Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
dacs_token \- manage DACS one\-time password token accounts
.SH "SYNOPSIS"
.HP \w'\fBdacs_token\fR\ 'u
\fBdacs_token\fR [\fI\m[blue]\fBdacsoptions\fR\m[]\&\s-2\u[1]\d\s+2\fR]
.SH "DESCRIPTION"
.PP
This program is part of the
\fBDACS\fR
suite\&.
.PP
The
\fBdacs_token\fR
web service provides limited account management operations on accounts recognized by
\m[blue]\fBlocal_token_authenticate\fR\m[]\&\s-2\u[2]\d\s+2, a
\fBDACS\fR
authentication module\&. Full administrative functionality is provided by
\fBdacstoken\fR; refer to
\m[blue]\fBdacstoken(1)\fR\m[]\&\s-2\u[3]\d\s+2
for detailed information about one\-time passwords, token devices, and user accounts\&. These accounts are completely separate from any other accounts and passwords\&.
.PP
Subject to configuration and valid authorization, this web service lets:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
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);
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
users change the
PIN
on their account;
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
users synchronize their account with their token; and
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBDACS\fR
administrators (see
\m[blue]\fBADMIN_IDENTITY\fR\m[]\&\s-2\u[4]\d\s+2) set, change, or remove the
PIN
on any account, synchronize an account with a token (removal depends on
\m[blue]\fBTOKEN_REQUIRES_PIN\fR\m[]\&\s-2\u[5]\d\s+2), or obtain the next
OTP
for a specified account;
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
anyone create and test a demonstration account (visit
\m[blue]\fBdacs\&.dss\&.ca\fR\m[]\&\s-2\u[6]\d\s+2
to try a live demonstration)\&.
.RE
.PP
Outside of demonstration mode operation, accounts are managed identically to
\m[blue]\fBdacstoken(1)\fR\m[]\&\s-2\u[3]\d\s+2
using the item types
auth_token,
auth_hotp_token, and
auth_totp_token\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBSecurity\fR
.ps -1
.br
.PP
The same account security stipulations as
\fBdacstoken\fR
apply\&.
.PP
The web service applies access controls internally; a
\fBDACS\fR
ACL can be added to further restrict its use\&. The internal rules are:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
A
\fBDACS\fR
administrator can synchronize any account without providing the account\*(Aqs
PIN; other users must provide the account\*(Aqs
PIN, if there is one\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
A
\fBDACS\fR
administrator can set, change, or remove (depending on
\m[blue]\fBTOKEN_REQUIRES_PIN\fR\m[]\&\s-2\u[5]\d\s+2) any account\*(Aqs
PIN; other users can set or change their account\*(Aqs
PIN
by:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
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
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
contacting a
\fBDACS\fR
administrator\&.
.RE
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
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\&.
.RE
.sp .5v
.RE
.PP
When validating a
HOTP
one\-time password, the
\m[blue]\fBTOKEN_HOTP_ACCEPT_WINDOW\fR\m[]\&\s-2\u[7]\d\s+2
configuration directive can be used to allow an account\*(Aqs counter value to automatically "catch up" to the token\*(Aqs\&.
.SH "OPTIONS"
.SS "Web Service Arguments"
.PP
In addition to the
\m[blue]\fBstandard CGI arguments\fR\m[]\&\s-2\u[8]\d\s+2,
\fBdacs_token\fR
understands the following CGI arguments:
.PP
\fICONFIRM_NEW_PIN\fR
.RS 4
Required with the
SET_PIN
operation, the value of this argument must be the same as the value of
\fICONFIRM_NEW_PIN\fR\&.
.RE
.PP
\fIOPERATION\fR
.RS 4
The following operations are supported:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
CURRENT
.sp
Unlike the other operations, this operation returns a
text/plain
MIME type, consisting of the current
\fImoving factor\fR
(i\&.e\&., the
HOTP
counter value or the
TOTP
interval value), followed by a space and the corresponding
OTP
for
\fIUSERNAME\fR\&. 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:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  1." 4.2
.\}
The user gives a username to the sign\-on procedure;
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  2." 4.2
.\}
The sign\-on procedure asks
\fBDACS\fR
for the
OTP
it expects the user\*(Aqs token to produce, based on the user\*(Aqs account parameters;
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  3." 4.2
.\}
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;
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  4." 4.2
.\}
The user continues the authentication procedure, perhaps by providing the token\*(Aqs next
OTP
or using another authentication method, such as a password\&.
.RE
.sp
The appropriateness of
TOTP
mode for mutual authentication depends on the
OTP
lifetime and other configuration parameters\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
SET_PIN
.sp
Set or change the
PIN
associated with the account for
\fIUSERNAME\fR\&. This operation requires the
\fINEW_PIN\fR,
\fICONFIRM_NEW_PIN\fR,
\fIMODE\fR, and
\fIUSERNAME\fR
arguments\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
SYNC
.sp
Synchronize the account for
\fIUSERNAME\fR
so that the next password produced by the token is expected to be valid\&. This operation requires the
\fIPASSWORD\fR,
\fIMODE\fR, and
\fIUSERNAME\fR
arguments\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
DEMO_CREATE
.sp
Create a demonstration account according to the given arguments, configuration values, and defaults\&. Required arguments:
\fIMODE\fR,
\fIKEY\fR,
\fIKEY_ENCODING\fR\&. Optional arguments:
\fINEW_PIN\fR,
\fICONFIRM_NEW_PIN\fR,
\fINDIGITS\fR,
\fIBASE\fR,
\fISERIAL\fR\&. Optional
HOTP
argument:
\fICOUNTER\fR\&. Optional
TOTP
arguments:
\fIDIGEST_NAME\fR,
\fITIME_STEP\fR\&. The
\fIKEY_ENCODING\fR
argument, which indicates how the
\fIKEY\fR
string has been encoded, must be one of
hex,
base32, or
none\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
DEMO_SYNC
.sp
Synchronize a demonstration account using
\fIUSERNAME\fR, a one\-time password or password sequence (\fISYNC\fR), and optional
\fIPIN\fR\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
DEMO_VALIDATE
.sp
Validate the given demonstration account (\fIUSERNAME\fR), one\-time password (\fIPASSWORD\fR), and
PIN
(\fIPIN\fR) in demonstration mode\&. No credentials are actually issued\&.
.RE
.sp
.RE
.PP
\fIMODE\fR
.RS 4
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\&.
.RE
.PP
\fINEW_PIN\fR
.RS 4
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]\fBTOKEN_REQUIRES_PIN\fR\m[]\&\s-2\u[5]\d\s+2, by omitting (or not providing a value for) both
\fINEW_PIN\fR
and
\fICONFIRM_NEW_PIN\fR\&.
.RE
.PP
\fIPASSWORD\fR
.RS 4
If the request is not accompanied by credentials for
\fIUSERNAME\fR
or an administrator identity, this one\-time password must validate against the expected value for
\fIUSERNAME\fR\&.
.RE
.PP
\fIPIN\fR
.RS 4
.RE
.PP
\fIUSERNAME\fR
.RS 4
The
\fBDACS\fR
username of interest\&.
.RE
.SH "DIAGNOSTICS"
.PP
The program exits
0
if everything was fine,
1
if an error occurred\&.
.SH "BUGS"
.PP
This version only provides self\-service operations for users and limited account management for a
\fBDACS\fR
administrator; administrators must use
\m[blue]\fBdacstoken(1)\fR\m[]\&\s-2\u[3]\d\s+2
for everything else\&. Full\-blown web\-based token account management should either be provided by
\fBdacs_token\fR
or
\m[blue]\fBdacs_admin(8)\fR\m[]\&\s-2\u[9]\d\s+2\&.
.PP
Demonstration mode accounts should be manually deleted from time to time\&.
.PP
The
\fIFORMAT\fR
is not understood\&. XML responses should be implemented\&.
.SH "SEE ALSO"
.PP
\m[blue]\fBdacstoken(1)\fR\m[]\&\s-2\u[3]\d\s+2,
\m[blue]\fBdacs\&.conf(5)\fR\m[]\&\s-2\u[10]\d\s+2,
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[11]\d\s+2\&. Also see the OTP token demonstration,
token_demo\&.html\&.
.SH "AUTHOR"
.PP
Distributed Systems Software (\m[blue]\fBwww\&.dss\&.ca\fR\m[]\&\s-2\u[12]\d\s+2)
.SH "COPYING"
.PP
Copyright \(co 2003\-2015 Distributed Systems Software\&. See the
\m[blue]\fBLICENSE\fR\m[]\&\s-2\u[13]\d\s+2
file that accompanies the distribution for licensing information\&.
.SH "NOTES"
.IP " 1." 4
dacsoptions
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html#dacsoptions
.RE
.IP " 2." 4
local_token_authenticate
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html#local_token_authenticate
.RE
.IP " 3." 4
dacstoken(1)
.RS 4
\%http://dacs.dss.ca/man/dacstoken.1.html
.RE
.IP " 4." 4
ADMIN_IDENTITY
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#ADMIN_IDENTITY
.RE
.IP " 5." 4
TOKEN_REQUIRES_PIN
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#TOKEN_REQUIRES_PIN
.RE
.IP " 6." 4
dacs.dss.ca
.RS 4
\%http://dacs.dss.ca
.RE
.IP " 7." 4
TOKEN_HOTP_ACCEPT_WINDOW
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#TOKEN_HOTP_ACCEPT_WINDOW
.RE
.IP " 8." 4
standard CGI arguments
.RS 4
\%http://dacs.dss.ca/man/dacs.services.8.html#standard_cgi_args
.RE
.IP " 9." 4
dacs_admin(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_admin.8.html
.RE
.IP "10." 4
dacs.conf(5)
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html
.RE
.IP "11." 4
dacs_authenticate(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html
.RE
.IP "12." 4
www.dss.ca
.RS 4
\%http://www.dss.ca
.RE
.IP "13." 4
LICENSE
.RS 4
\%http://dacs.dss.ca/man/../misc/LICENSE
.RE