.\" 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: dacstoken
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 02/19/2019
.\"    Manual: DACS Commands Manual
.\"    Source: DACS 1.4.40
.\"  Language: English
.\"
.TH "DACSTOKEN" "1" "02/19/2019" "DACS 1.4.40" "DACS Commands 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"
dacstoken \- administer hash\-based one\-time passwords
.SH "SYNOPSIS"
.HP \w'\fBdacstoken\fR\ 'u
\fBdacstoken\fR [\fI\m[blue]\fBdacsoptions\fR\m[]\&\s-2\u[1]\d\s+2\fR] [\fB\-all\fR] [\fB\-base\ \fR\fB\fInum\fR\fR] [\fB\-counter\fR\ \fInum\fR] [\fB\-digits\ \fR\fB\fInum\fR\fR]
.br
[\fB\-disable\fR | \fB\-enable\fR] [\fB\-hotp\-window\ \fR\fB\fInum\fR\fR] [\fB\-ignore\-key\-length\fR]
.br
[\fB\-inkeys\ \fR\fB\fIitem_type\fR\fR] [\fB\-issuer\ \fR\fB\fIname\fR\fR] [[\fB\-key\fR\ \fIkeyval\fR] | [\fB\-key\-enc\fR\ \fIenc\fR] | [\fB\-key\-file\fR\ \fIfilename\fR] | [\fB\-key\-prompt\fR]
.br
] [\fB\-mode\ \fR\fB\fIotp\-mode\fR\fR] [\fB\-nl\fR] [\fB\-outkeys\ \fR\fB\fIitem_type\fR\fR] [[\fB\-pin\fR\ \fIpinval\fR] | [\fB\-pin\-file\fR\ \fIfilename\fR] | [\fB\-pin\-prompt\fR]]
.br
[\fB\-pin\-constraints\fR\ \fIstr\fR] [\fB\-rnd\fR] [\fB\-seed\ \fR\fB\fIstr\fR\fR] [\fB\-serial\ \fR\fB\fIstr\fR\fR] [\fB\-totp\-delta\ \fR\fB\fInum\fR\fR] [\fB\-totp\-drift\ \fR\fB\fInwindows\fR\fR]
.br
[\fB\-totp\-hash\ \fR\fB\fIalg\fR\fR] [\fB\-totp\-time\ \fR\fB\fIsecs\fR\fR] [\fB\-totp\-timestep\ \fR\fB\fIsecs\fR\fR] [\fB\-vfs\ \fR\fB\fIvfs_uri\fR\fR] [\fIop\-spec\fR] [\fIusername\fR]
.SH "DESCRIPTION"
.PP
This program is part of the
\fBDACS\fR
suite\&.
.PP
The
\fBdacstoken\fR
utility administers
\fBDACS\fR
accounts associated with one\-time password (OTP) generating devices (\fItokens\fR) or software\-based clients\&. Using command line options, it also computes
OTP
values; token account parameters can be overridden, but accounts are not even required\&.
.PP
Strong, two\-factor authentication can be provided when
\m[blue]\fBdacs_authenticate\fR\m[]\&\s-2\u[2]\d\s+2
is configured to use the
\m[blue]\fBlocal_token_authenticate\fR\m[]\&\s-2\u[3]\d\s+2
authentication module or when
\fBdacstoken\fR
is used as a standalone program to validate passwords\&. Two kinds of one\-time password algorithms are supported: the HMAC\-based one\-time password mode (HOTP), based on an event counter and specified by
\m[blue]\fBRFC 4226\fR\m[]\&\s-2\u[4]\d\s+2, and the time\-based one\-time password mode (TOTP), as specified by
\m[blue]\fBRFC 6238\fR\m[]\&\s-2\u[5]\d\s+2\&. Additional operational modes called
OCRA
(\fIOATH Challenge\-Response Algorithms\fR), described in
\m[blue]\fBRFC 6287\fR\m[]\&\s-2\u[6]\d\s+2, are not yet fully supported\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
This version of
\fBdacstoken\fR
incorporates many changes that are not backward compatible with release
1\&.4\&.24a
and earlier\&. Some command line flags function differently, and the format of the account file has changed\&. If you have used this command in earlier releases, please make a backup copy of your token account file and review this manual page carefully before proceeding (note the
\m[blue]\fB\fB\-convert\fR flag\fR\m[]\&\s-2\u[7]\d\s+2
in particular)\&.
.sp .5v
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBImportant\fR
.ps -1
.br
.PP
No vendor\-supplied software is required by
\fBdacstoken\fR
to supply its functionality\&. The devices currently supported do not need any registration or configuration interaction with vendors and
\fBdacstoken\fR
\fIdoes not interact with vendors\*(Aq servers or use any proprietary software\fR\&. Vendor\-supplied software may be required to perform initialization or configuration for other token devices, however, and
\fBdacstoken\fR
does not provide such support for them\&.
.sp .5v
.RE
.PP
Each token device generally corresponds to exactly one account that is managed by
\fBdacstoken\fR, although some vendors produce tokens that can support multiple accounts\&.
.PP
To summarize, this utility:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
creates and administers
\fBDACS\fR
accounts associated with counter\-based and time\-based one\-time passwords
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
provides validation and testing functionality
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
provides a command line authentication capability
.RE
.sp
.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
Only the
\fBDACS\fR
administrator should be able to successfully run this program from the command line\&. Because
\fBDACS\fR
keys and configuration files, including the file used to store accounts, must be restricted to the administrator, this will normally be the case, but a careful administrator will set file permissions to deny access to all other users\&.
.sp .5v
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
The
\m[blue]\fBdacs_token(8)\fR\m[]\&\s-2\u[8]\d\s+2
web service provides users with limited self\-service functionality to set or reset their account
PIN
and synchronize their token\&. It also has a demonstration mode to simplify testing and evaluation\&.
.sp .5v
.RE
.SS "PINs (Account Passwords)"
.PP
A
\fBdacstoken\fR
account can optionally have a
PIN
(i\&.e\&., a password) associated with it\&. To authenticate against such an account, a user must provide the one\-time password produced by the token
\fIand\fR
the
PIN\&. The
\m[blue]\fBTOKEN_REQUIRES_PIN\fR\m[]\&\s-2\u[9]\d\s+2
configuration directive determines whether a
PIN
must be provided when creating or importing an account\&. By default, a
PIN
is required\&. The directive does not apply in conjunction with the
\fB\-delpin\fR
flag, since only an administrator should be able to perform that function\&.
.PP
A hash of the
PIN
is stored in the account record\&. The
PIN
is not stored\&. The same method used by
\m[blue]\fBdacspasswd(1)\fR\m[]\&\s-2\u[10]\d\s+2
and
\m[blue]\fBdacs_passwd(8)\fR\m[]\&\s-2\u[11]\d\s+2
is applied, and depends on the
\m[blue]\fBPASSWORD_DIGEST\fR\m[]\&\s-2\u[12]\d\s+2
and
\m[blue]\fBPASSWORD_SALT_PREFIX\fR\m[]\&\s-2\u[13]\d\s+2
directives in effect\&. If
\m[blue]\fBPASSWORD_DIGEST\fR\m[]\&\s-2\u[12]\d\s+2
is configured, that algorithm is used, otherwise a compile\-time default (SHA\-1) is used\&. If a user forgets the
PIN, the old one cannot be recovered so it must either be deleted or a new one must be set\&.
.PP
Some token devices and client software have a
PIN
feature\&. The user must enter a
PIN
into the device before the device will emit a one\-time password\&. This "device
PIN" is completely distinct from the account
PIN
(a server\-side password) that is managed by
\fBdacstoken\fR, and this manual is only concerned with the
\fBdacstoken\fR
PIN\&. The device
PIN
should always be used when possible; the
\fBdacstoken\fR
PIN
is strongly recommended and is required for two\-factor authentication (unless an additional authentication factor is applied in some other way)\&.
.PP
Since only the administrator is allowed to run this command, no restrictions are imposed on the length or quality of the
PINs
that the administrator supplies; a warning message will be emitted, however, if the password is considered to be weak as determined by the
\m[blue]\fBPASSWORD_CONSTRAINTS\fR\m[]\&\s-2\u[14]\d\s+2
directive\&.
.SS "One\-Time Passwords (OTPs)"
.PP
Both kinds of one\-time password device compute a password value by employing a secure keyed hash algorithm (\m[blue]\fBRFC 2104\fR\m[]\&\s-2\u[15]\d\s+2,
\m[blue]\fBFIPS 198\fR\m[]\&\s-2\u[16]\d\s+2)\&. In the counter\-based method, the device and server share a secret key and a counter value which are hashed to yield a numerical value displayed in a certain radix with a certain number of digits\&. Successful authentication requires the device and server to compute matching passwords\&. Each time the device produces a password, it increments its counter\&. When the server receives a matching password, it increments its counter\&. Because it is possible for the two counters to become unsynchronized, the server\*(Aqs matching algorithm will typically allow a client\*(Aqs password to fall within a "window" of counter values\&. The time\-based method is similar, the main difference being that the current Unix time (as returned by
\m[blue]\fBtime(3)\fR\m[]\&\s-2\u[17]\d\s+2, for instance) is used to establish a "time\-step window" that serves as a counter value in the computation of the secure hash\&. Because the real\-time clocks on the device and server may not be sufficiently synchronized, the server\*(Aqs matching algorithm must also allow a client\*(Aqs password to fall within some number of time\-step windows for these devices\&.
.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
A token may be assigned a permanent secret key (sometimes called an
OTP seed) by its manufacturer or the key may be programmable\&. This secret key is used by the token\*(Aqs password generation procedure and it is critical that it be kept private\&. If the token is not programmable, the key is obtained from the vendor (for a
HOTP
token, typically by providing the device\*(Aqs serial number and any three consecutive passwords)\&. A record of each mapping from serial number to secret key should be kept in a secure location\&.
.PP
If the secret key is programmable, as it is likely to be with a software client, it is required to be at least
\fB128\fR
bits in length; a minimum of
\fB160 bits\fR
is recommended (see
\m[blue]\fBRFC 4226\fR\m[]\&\s-2\u[4]\d\s+2) and by default the key is represented as a 16 (or more) character long hexadecimal string\&. The minimum length requirement can be overridden by the
\fB\-ignore\-key\-length\fR
flag, and the algorithm used to encode the key can be specified using the
\fB\-key\-enc\fR
flag\&. The key must be syntactically correct for the specified encoding algorithm and should be obtained from a cryptographic\-quality source of random bits\&. Some clients may be capable of generating a suitable key, but you may use
\m[blue]\fBdacsexpr(1)\fR\m[]\&\s-2\u[18]\d\s+2:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacsexpr \-e "random(string, 20)"
"bb2504780e8075a49bd88891b228fc7216ac18d9"
.fi
.if n \{\
.RE
.\}
.sp .5v
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBTip\fR
.ps -1
.br
.PP
Tokens can be used for authentication purposes other than computer sign on\&. For example, by providing an account number,
PIN, and token value, customers can quickly be authenticated over the phone, reducing or eliminating the need for expensive and time\-consuming security questions\&.
.sp .5v
.RE
.PP
One\-time password devices and applications have the following operational parameters\&. These parameters determine the password sequence that is generated\&. Some operational parameters may be fixed (by the relevant standard or due to the implementation), while others may be partially or completely configurable by the user\&. Please refer to the references and manufacturers\*(Aq documentation for details\&.
.PP
base
.RS 4
The radix in which passwords are displayed\&.
.RE
.PP
counter
.RS 4
For
HOTP
mode only, the current counter value\&.
.RE
.PP
digits
.RS 4
The number of digits in each one\-time password\&.
.RE
.PP
key
.RS 4
The secret key (OTP
seed)\&.
.RE
.PP
serial number
.RS 4
A unique identifier or name for the device\&.
.RE
.PP
time step size
.RS 4
For
TOTP
mode only, the width of each time interval, in seconds\&. The same password will be generated within a given interval; i\&.e\&., this is the "lifetime" or validity period of each
TOTP
password\&.
.RE
.PP
In addition to these parameters,
\fBdacstoken\fR
employs several per\-account (i\&.e\&., per\-device) parameters:
.PP
accept\-window
.RS 4
When validating a
HOTP
password, the maximum number of passwords to consider after the expected password\&.
.RE
.PP
drift
.RS 4
For
TOTP
mode only, the number of seconds by which to adjust the server\*(Aqs clock forward or backward to better synchronize it with the device\&. This is used to compensate for tokens or client software whose clocks are not well synchronized with the server\*(Aqs\&.
.RE
.PP
drift\-window
.RS 4
For
TOTP
mode only, but analogous to the
accept\-window, the maximum number of intervals (each of the time step size) to search forward and backward when validating against a given password\&.
.RE
.PP
sync\-otps
.RS 4
For
HOTP
mode only, the number of consecutive one\-time passwords required to synchronize the account with the device\&.
.RE
.PP
username
.RS 4
The name of the
\fBDACS\fR
account bound to the device\&.
.RE
.PP
Authentication based on one\-time password devices has the following advantages:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Each time a user authenticates, a different password will be generated (with high probability); users cannot therefore jot down "the password" because the password is always changing; users cannot forget their password;
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Once used, a
HOTP
mode password is immediately "consumed" and is unlikely to be used again for a long time; with suitable configuration parameters, a
TOTP
mode password automatically "expires" within a relatively short time interval and is unlikely to be used again for a long time;
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
If no correction for clock drift is required, a
TOTP
mode account can have read\-only operation;
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Because the password is unlikely to be an easily\-guessed number or string, it should be stronger than most user\-selected passwords;
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
A
HOTP
token can be the basis of a mutual ("bidirectional") authentication method; the server shows the user his token\*(Aqs next password to confirm its identity (with both parties advancing their counters), then the client shows the server the next password to confirm his identity;
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Should a key sniffer be installed on the user\*(Aqs computer, a sniffed password does not do an attacker any good unless a
\m[blue]\fBman\-in\-the\-middle attack\fR\m[]\&\s-2\u[19]\d\s+2
is possible; given
\fIN\fR
consecutive passwords it is still very difficult to compute password
\fIN + 1\fR
without knowing the secret key;
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
It is more difficult for users to share an account (although users might sometimes view this as an inconvenience);
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
If a
\fBdacstoken\fR
PIN
is assigned to an account and an attacker obtains the account\*(Aqs token, it is still difficult for the attacker to authenticate without knowing the
PIN;
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
A quick and immediately effective way to disable an account is by simply seizing a hardware token (e\&.g\&., if an employee is fired), although an account can be disabled by this program or using the
\m[blue]\fBrevocation list\fR\m[]\&\s-2\u[20]\d\s+2;
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
In the case of a software client that runs on a mobile device, such as a phone or PDA, users are already carrying the device with them; free clients are available, so there may be no additional cost (note that mobile devices may not offer the same tamper\-resistance, durability, key secrecy, clock accuracy, etc\&. of a hardware token)\&.
.RE
.PP
One\-time password devices have the following potential disadvantages:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
There is a one\-time expense for a hardware token (depending on the purchase volume, you can expect to pay $10\-$100 USD each), and there is the possibility of having to replace a lost or broken token, or a token\*(Aqs battery (some units have a non\-replaceable battery, making them disposable after a few years);
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Initial configuration is somewhat more difficult than with other authentication methods, and users unfamiliar with the devices will have to be instructed on their use;
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Although they are typically quite small (e\&.g\&., 5cm x 2cm x 1cm) and can be attached to a keychain or lanyard, or kept in a wallet, users may wince at having to carry a token around with them;
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Users can forget to have their token with them or lose the token;
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
A mobile device (with a software client) is probably a likely target for theft, more so than a hardware token (hence the extra importance of a
PIN
for this device);
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Unlike a hardware token where the key is burned into inaccessible, tamper\-proof memory, the key configured into a software client is likely to be readable by its owner, making sharing of the account possible;
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Entering a 40 character or longer seed value into a mobile device can be frustrating and prone to error;
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Once a
TOTP
device generates a password, a new password cannot be generated until the next time\-step window, requiring the user to wait 30 (or possibly 60) seconds (e\&.g\&., if an entry error is made);
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Some devices are difficult to read in low\-light conditions; presbyopic users and those with impaired vision may have difficulty reading the display\&.
.RE
.sp
.SS "Accounts"
.PP
The accounts managed by
\fBdacstoken\fR
are completely separate from the accounts used by
\m[blue]\fBlocal_passwd_authenticate\fR\m[]\&\s-2\u[21]\d\s+2
or any other
\fBDACS\fR
authentication module\&.
.PP
Accounts for
HOTP
and
TOTP
devices may either be stored together or kept separate\&. If the virtual filestore item type
auth_hotp_token
is defined, it is only used for accounts associated with
HOTP
tokens\&. Similarly, if the virtual filestore item type
auth_totp_token
is defined, it is only used for accounts associated with
TOTP
tokens\&. If either item type is not defined, accounts are accessed through
\fBDACS\*(Aqs\fR
virtual filestore using item type
auth_token\&. It is assumed that file permissions on the account databases are such that all access is limited to the administrator and
\fBlocal_token_authenticate\fR\&.
.PP
If accounts for the two device types are
\fIcombined\fR, because each username for an authentication method must be unique, if an individual has both types of token they must be assigned different usernames\&. So, for example, if Auggie has one
HOTP
token and one
TOTP
token, the former might correspond to the username
auggie\-hotp
and the latter to
auggie\-totp; the sign\-on form might include a device\-mode input which would allow Auggie to simply type "auggie" in the username field and
JavaScript
to automatically append the appropriate suffix based on the select device mode\&. An obvious disadvantage of this configuration is that it results in two different
\fBDACS\fR
identities for the same individual; this would have to be remembered if an access control rule needed to identify Auggie explicitly\&. If both tokens should map to the same
\fBDACS\fR
identity, the
Auth
clause could strip the suffix off after successful authentication, but the administrator would then need to beware of the case of two different Auggies, each using a different device type\&.
.PP
Configuring both the
auth_hotp_token
and
auth_totp_token
item types (or just one of them and
auth_token) keeps the accounts separate and allows the same username to be used for both types of devices\&. Auggie could therefore have an account record with the same username for both device types\&. This approach requires the device mode to be specified when an operation is requested so that the correct item type can be used; this means that users must know which type of device they are using (perhaps by afixing a label to it)\&. Refer to important details regarding
\m[blue]\fB\fBDACS\fR identities\fR\m[]\&\s-2\u[22]\d\s+2\&.
.PP
The
\fB\-vfs\fR
can be used to configure or reconfigure the item types\&.
.PP
Multiple instances of each item type can exist, provided the correct one for
\fBdacstoken\fR
to use can be determined at run time and specified through a
\m[blue]\fBVFS\fR\m[]\&\s-2\u[23]\d\s+2
directive or
\fB\-vfs\fR
flag\&.
.PP
Only keys that meet the minimum key length requirement (\fB16\fR
bytes) may be stored with account information (e\&.g\&., with
\fB\-set\fR
or
\fB\-import\fR)\&. In other contexts, the requirement is not enforced\&.
.PP
The secret key is always encrypted and converted to a base\-64 representation when it is stored in the account file by
\fBdacstoken\fR\&. The virtual filestore item type
auth_token_keys
identifies the encryption keys for
\fBdacstoken\fR
to use; the
\fB\-inkeys\fR
and
\fB\-outkeys\fR
flags specify alternatives (see
\m[blue]\fBdacskey(1)\fR\m[]\&\s-2\u[24]\d\s+2)\&. If the encryption keys are lost, the secret keys are practically unrecoverable\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBImportant\fR
.ps -1
.br
.PP
If an attacker discovers a secret key, generating usable passwords without possessing the token will not be difficult\&. For at least some hardware tokens, the key is burned in to the device and cannot be changed; in this case, if the key is leaked the device should be destroyed\&. If a token is lost, the corresponding account should be disabled\&. In the event an attacker finds a lost token or discovers a secret key, having a strong
PIN
associated with the account will make it difficult for the attacker to gain access\&.
.sp .5v
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBImportant\fR
.ps -1
.br
.PP
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
This authentication method has been tested against the following
OTP
products:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\m[blue]\fBAuthenex A\-Key\(rg 3600\fR\m[]\&\s-2\u[25]\d\s+2
one\-time password (HOTP) hardware token;
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\m[blue]\fBFeitian Technologies\fR\m[]\&\s-2\u[26]\d\s+2
OTP C100
and
OTP C200
one\-time password hardware tokens, provided by
\m[blue]\fBHyperSecu Information Systems\fR\m[]\&\s-2\u[27]\d\s+2; and
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\m[blue]\fBGoogle Authenticator\fR\m[]\&\s-2\u[28]\d\s+2\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The
\m[blue]\fBopen source\fR\m[]\&\s-2\u[29]\d\s+2
\m[blue]\fBFreeOTP Authenticator\fR\m[]\&\s-2\u[30]\d\s+2
by
\m[blue]\fBRed Hat\fR\m[]\&\s-2\u[31]\d\s+2, which is available for a variety of platforms\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\m[blue]\fBOATH Token\fR\m[]\&\s-2\u[32]\d\s+2
software application by Archie Cobbs, which implements both
HOTP
and
TOTP
on the
\m[blue]\fBiPod Touch, iPhone, and iPad\fR\m[]\&\s-2\u[33]\d\s+2\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The
\m[blue]\fBOTP Auth\fR\m[]\&\s-2\u[34]\d\s+2
software application for the iPod Touch, iPhone, and iPad by Roland Moers\&.
.RE
.sp
There are many other free software implementations\&. Other manufacturers interested in having their products supported by
\fBDACS\fR
are welcome to
\m[blue]\fBcontact\fR\m[]\&\s-2\u[35]\d\s+2
Dss\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\m[blue]\fBPhoto\fR\m[]\&\s-2\u[36]\d\s+2:
Feitian OTP C200,
iPod Touch
with the
OATH Token
app,
Authenex A\-Key\(rg 3600
(clockwise from top left)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Although this implementation should work with similar, conformant products, only these products are officially supported by
\fBDACS\fR\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Hardware tokens can be purchased directly from the vendors\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Any problems with using tokens to authenticate through
\fBDACS\fR
are not the responsibility of the token vendor\&.
.RE
.sp .5v
.RE
.SS "Importing and Exporting OTP Accounts"
.PP
Descriptions of accounts and their tokens can be loaded or dumped (refer to the
\fB\-import\fR
and
\fB\-export\fR
flags)\&. This simplifies provisioning, backup, and portability\&. The account information can be written in a simple, application\-specific (almost) XML format, or Google\*(Aqs
\m[blue]\fBKeyUriFormat\fR\m[]\&\s-2\u[37]\d\s+2, which is understood by several
OTP
applications\&.
.PP
The
\fB\-format\fR
flag (see
\m[blue]\fB\fIdacsoptions\fR\fR\m[]\&\s-2\u[38]\d\s+2) can be used to select the
xml
format (the default) or the
uri
format for export\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
At present, the
uri
format cannot be imported by
\fBdacstoken\fR\&.
.sp .5v
.RE
.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
Because imported records include the unencrypted secret keys for the
OTP
devices, the exported file should be kept encrypted (e\&.g\&., using
\fBopenssl\fR) or at least have appropriate file permissions\&.
.sp .5v
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
An official standard format for
OTP
device provisioning is being developed\&. This format may be understood by a future version of
\fBdacstoken\fR, or a conversion utility may be written\&. The standard format is likely to be considerably more complex than the
\fBDACS\fR
format\&.
.sp .5v
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBXML Provisioning Format\fR
.RS 4
.PP
The XML format understood by
\fBdacstoken\fR
consists of a root element ("otp_tokens"), followed by zero or more "otp_token" elements, one per line, each with required and optional attributes (described below)\&. The XML declaration must be omitted\&. Leading whitespace and blank lines are ignored, as are single line XML comments\&. Additionally, lines having a "#" as the first non\-whitespace character are ignored\&. Optional attributes that are not present are assigned default values\&. The default digest algorithm is
SHA\-1\&. Short attribute names are used to save space\&. Unrecognized attributes, and attributes irrelevant to the device mode, are ignored\&. Single or double quote characters (or both) within XML attribute values must be replaced by the corresponding entity reference ("&apos;" and "&quot;", respectively), as must the "<" (less than) and "&" (ampersand) characters\&. A ">" (greater than) character may optionally be replaced by a "&gt;" sequence, but no other entity references are recognized\&.
.PP
Recognized attributes are:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
b:
  \fIbase\fR
  \-\- radix for OTP value
  [Optional:
  \fB10\fR (default),
  \fB16\fR, or \fB32\fR]
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
c:
  \fIcounter\fR
  \-\- current counter value for HOTP, in hex if preceded
  by "0x" (or "0X"), decimal otherwise
  [Optional:
  default is \fB0\fR]
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
d:
  \fIOTP device mode\fR
  \-\- "c" (for HOTP)
  or "t" (for TOTP)
  [Required]
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
dn:
  \fIdigest\-name\fR
  \-\- one of the Secure Hash Algorithms
  [Optional:
  SHA\-1 (default),
  SHA224, SHA256,
  SHA384, SHA512]
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
dr:
  \fIclock\-drift\fR
  \-\- clock adjustment, in seconds, for TOTP
  [Optional]
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
ek:
  \fIencrypted\-key\fR
  \-\- encrypted secret key, base\-64 encoded
  [Required:
  OTP account records only]
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
en:
  \fIenabled\-status\fR
  \-\- \fB1\fR for enabled,
  \fB0\fR for disabled
  [Required]
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
k:
  \fIplaintext\-key\fR
  \-\- unencrypted secret key
  [Required]
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
lu:
  \fIlast\-update\fR
  \-\- Unix time of last record update
  [Optional: default is current time]
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
nd:
  \fIndigits\fR
  \-\- number of digits for OTP value
  [Optional:
  default is \fB6\fR for HOTP,
  \fB8\fR for TOTP]
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
p:
  \fIplaintext\-PIN\fR
  \-\- plaintext PIN value for the account
  [Required:
  unless ph is present,
  for import only]
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
ph:
  \fIhashed\-PIN\fR
  \-\- hashed PIN value for the account
  [Optional:
  generated by \fBdacstoken\fR
  for export and OTP account files only]
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
s:
  \fIserial\-number\fR
  \-\- unique identifier string for the device
  [Required]
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
ts:
  \fItime\-step\fR
  \-\- time\-step value, in seconds, for TOTP
  [Optional:
  default is \fB30\fR]
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
u:
  \fIusername\fR
  \-\- a valid \fBDACS\fR username associated with this account
  [Required]
.RE
.PP
The following example describes two accounts that might be created using the
\fB\-import\fR
flag:
.sp
.if n \{\
.RS 4
.\}
.nf
<otp_tokens>
<!\-\- Staff OTP tokens for DACS authentication \-\->
<otp_token u="ietf" d="t" en="1" s="totp\-ietf &quot;draft&quot;" k="3132333435363738393031323334353637383930" dn="SHA1" ts="30"/>
<otp_token u="ipod\-c" d="c" en="1" s="ipodc\-9C841SD4203" k="19c0a3519a89b4a8034c5b9306db" dn="SHA1" c="0" nd="6" b="10"/>
</otp_tokens>
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBKeyUriFormat Provisioning Format\fR
.RS 4
.PP
The
\m[blue]\fBKeyUriFormat\fR\m[]\&\s-2\u[37]\d\s+2
provisioning format is supported by several OTP clients, such as
\m[blue]\fBFreeOTP\fR\m[]\&\s-2\u[30]\d\s+2
and
\m[blue]\fBGoogle Authenticator\fR\m[]\&\s-2\u[28]\d\s+2\&. In this format, a
URI
describes the current state of an account\&. The
URI
can be encoded into a
\m[blue]\fBQR Code\fR\m[]\&\s-2\u[39]\d\s+2
image (a two\-dimensional barcode), which these and other
OTP
clients can recognize and conveniently and correctly import using a device\*(Aqs camera\&. Also, software such as
\fBzbarimg\fR, a component of the
\m[blue]\fBZBar\fR\m[]\&\s-2\u[40]\d\s+2
suite, can scan and decode barcodes that it finds in image files\&.
.PP
An account can be created by
\fBdacstoken\fR, exported as a
KeyUriFormat
URI, converted to a QR Code image, sent to a user (e\&.g\&., via email or an IM) or displayed on a secure web page, and finally imported by a user\*(Aqs client software\&. A QR Code generator that has been successfully used for this purpose with the iPhone is
\fBqrencode\fR, which is distributed with the
\m[blue]\fBlibqrencode library\fR\m[]\&\s-2\u[41]\d\s+2\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNotes\fR
.ps -1
.br
.PP
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Depending on QR Code generation parameters, there is a limit to the length of the
KeyUriFormat
that can be encoded\&. The maximum
URI
length is likely to be around 2,953 characters\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The
\fIsecret\fR
query parameter (the
OTP
seed) is
\m[blue]\fBbase\-32 encoded\fR\m[]\&\s-2\u[42]\d\s+2
without padding\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
A newline should not be encoded in the barcode\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The
\fB\-issuer\fR
flag can be used to specify the name of the token issuer\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
A QR barcode can be easily copied by an attacker for reuse\&.
.RE
.sp .5v
.RE
.RE
.SH "OPTIONS"
.PP
In addition to the standard
\m[blue]\fB\fIdacsoptions\fR\fR\m[]\&\s-2\u[1]\d\s+2, a lengthy list of command line flags are recognized\&. When a
\fIusername\fR
is given, default values associated with that account are used, otherwise recommended or implementation\-specific defaults are used\&. These default values can usually be overridden on the command line\&. Some flags are only allowed with a particular token mode (e\&.g\&.,
\fB\-counter\fR,
\fB\-totp\-show\fR) and their appearance implies that mode, making the
\fB\-mode\fR
flag unnecessary; other flags are mode independent (e\&.g\&.,
\fB\-delete\fR,
\fB\-enable\fR)\&. It is an error to use a mutually incompatible flag combination\&. Flags that are meaningless with the selected operation are ignored, although they still imply a mode\&. Hexadecimal values are case insensitive\&. If a counter value is required but unspecified (e\&.g\&., when creating an account), an initial counter value of zero is used\&.
.PP
The
\fIop\-spec\fR
specifies the operation to be performed, together with zero or more
\fImodifier\fR
flags\&. If
\fIop\-spec\fR
is missing, the
\fB\-list\fR
operation is performed\&. An
\fIop\-spec\fR
is one of the following:
.PP
.PP
\fB\-auth\fR \fIotp\-value\fR
.RS 4
This flag is like
\m[blue]\fB\fB\-validate\fR\fR\m[]\&\s-2\u[43]\d\s+2, except:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
a
\fIusername\fR
is required, from which all parameters are obtained (such as the key);
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
if the account has a
PIN, it must be provided;
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
if the account is for a
HOTP
token, the counter will be updated if authentication is successful\&.
.RE
.sp
An exit status of zero indicates successful authentication, while any other value means authentication failed\&.
.RE
.PP
\fB\-convert \fR\fB\fIfilename\fR\fR
.RS 4
Load an older format (prior to release 1\&.4\&.25) token account file from
\fIfilename\fR
("\-" means to read from
stdin), convert it to the newer format, and write it to
stdout
(as by
\fB\-export\fR)\&. This flag is deprecated and this capability will be removed in a future release of
\fBDACS\fR\&.
.RE
.PP
\fB\-create\fR
.RS 4
Create an account for
\fIusername\fR, which must not already exist\&. In other respects it works like
\m[blue]\fB\fB\-set\fR\fR\m[]\&\s-2\u[44]\d\s+2\&. When creating a new account,
\fB\-serial\fR
is required and
\fB\-key\fR
is implied\&. If no
\fB\-enable\fR
flag is provided when creating an account,
\fB\-disable\fR
is implied\&. If no
\fB\-counter\fR
flag is provided, a default of zero is used\&. If one of the
PIN
flags is present, the given
PIN
will be assigned to the account, otherwise the account will not have a
PIN
(or the existing
PIN
will not be changed)\&.
.RE
.PP
\fB\-current\fR
.RS 4
Display the current moving factor (i\&.e\&., the counter value for
HOTP
or the interval value for
TOTP) and expected
OTP
for
\fIusername\fR\&. For
HOTP, the counter is advanced\&. All parameters are taken from the account\&.
.RE
.PP
\fB\-delete\fR
.RS 4
Delete the account for
\fIusername\fR\&. The device\*(Aqs secret key and other operational parameters will be lost\&.
.RE
.PP
\fB\-delpin\fR
.RS 4
Delete the
PIN, if present, on the account for
\fIusername\fR, leaving the account without a
PIN\&.
.RE
.PP
\fB\-export\fR
.RS 4
Write information about all accounts, or only one account if
\fIusername\fR
is given, to
stdout\&. If a mode is selected, however, only accounts having that mode will be written\&. This information may be reloaded using
\fB\-import\fR
or
\fB\-import\-replace\fR\&. The output should be stored in an encrypted form, or at the very least have its file permissions set appropriately\&. For example:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacstoken \-uj EXAMPLE \-export | openssl enc \-aes\-256\-cbc > dacstoken\-exported\&.enc
.fi
.if n \{\
.RE
.\}
.sp
Later, you might do something like:
.sp
.if n \{\
.RS 4
.\}
.nf
% openssl enc \-d \-aes\-256\-cbc < dacstoken\-exported\&.enc | dacstoken \-uj EXAMPLE \-import \-
.fi
.if n \{\
.RE
.\}
.sp
.RE
.PP
\fB\-h\fR
.br
\fB\-help\fR
.RS 4
Display a help message and exit\&.
.RE
.PP
\fB\-hotp\-show\fR \fInum\fR
.RS 4
Display
\fInum\fR
consecutive
HOTP
passwords from a given counter value and key\&. The
\fB\-counter\fR
flag can be used to specify an initial counter value\&. The key can be specified using
\fB\-key\fR,
\fB\-key\-file\fR, or
\fB\-key\-prompt\fR\&. If a
\fIusername\fR
is provided, the initial counter value and key are obtained from the user\*(Aqs
HOTP
account, unless either value is overridden on the command line; the account\*(Aqs stored counter value is not modified\&. This is mainly intended for debugging purposes\&.
.RE
.PP
\fB\-import \fR\fB\fIfilename\fR\fR
.br
\fB\-import\-replace \fR\fB\fIfilename\fR\fR
.RS 4
Load account and token information from
\fIfilename\fR; if
\fIfilename\fR
is "\-",
stdin
is read\&. If a mode is selected, only accounts having that mode will be read\&. With
\fB\-import\fR
it is an error if an imported account already exists, and processing stops;
\fB\-import\-replace\fR
will replace an existing account with imported data\&.
.RE
.PP
\fB\-issuer \fR\fB\fIname\fR\fR
.RS 4
Use the string
\fIname\fR
as the token issuer when exporting an account in
KeyUriFormat
format\&.
.RE
.PP
\fB\-l\fR
.br
\fB\-list\fR
.br
\fB\-L\fR
.br
\fB\-long\fR
.RS 4
If
\fIusername\fR
is provided, list the corresponding account (it is an error if the account does not exist)\&. Otherwise, if the
\fB\-serial\fR
flag is given, list the account with the specified serial number\&. If neither argument is given, list all accounts having the mode specified by the
\fB\-mode\fR
flag, or if
\fB\-mode\fR
is absent, all accounts\&. If
\fB\-l\fR
(equivalently,
\fB\-list\fR) is repeated, or with the
\fB\-long\fR
flag (equivalently,
\fB\-L\fR), more detail is displayed for each account:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
account name,.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
device type (mode of operation),.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
account status,.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
device serial number,.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
counter value (for HOTP),.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
clock drift value (for TOTP),.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
whether or not the account has a PIN
(indicated by a "+" or "\-" symbol), and
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
the time and date of the account\*(Aqs last modification\&..RE
.sp
Examples:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacstoken \-uj EXAMPLE \-long
bobo,hotp,disabled,"foo17",000000000000000a,\-PIN,10\-Sep\-2014@10:57:20
auggie,totp,enabled,"c200\-2009234172055",0,\-PIN,20\-May\-2010@14:20:01
% dacstoken \-uj EXAMPLE \-mode hotp \-L
bobo,hotp,disabled,"foo17",000000000000000a,\-PIN,10\-Sep\-2014@10:57:20
.fi
.if n \{\
.RE
.\}
.sp
.RE
.PP
\fB\-rename\fR \fInew\-username\fR
.RS 4
Rename the existing account for
\fIusername\fR
to be
\fInew\-username\fR, and modify the new account using command line arguments (as with
\m[blue]\fB\fB\-set\fR\fR\m[]\&\s-2\u[44]\d\s+2)\&. As this requires two steps that are not done atomically, if an error occurs it is possible for the new account to be created and the old account to still exist\&.
.RE
.PP
\fB\-set\fR
.RS 4
The
\fB\-set\fR
flag is used to modify the existing account for
\fIusername\fR
based on one or more modifier arguments (\fB\-base\fR,
\fB\-counter\fR,
\fB\-digits\fR,
\fB\-disable\fR
or
\fB\-enable\fR,
\fB\-key\fR
(or
\fB\-key\-file\fR
or
\fB\-key\-prompt\fR),
\fB\-pin\fR
(or
\fB\-pin\-file\fR
or
\fB\-pin\-prompt\fR), or
\fB\-serial\fR)\&. The mode can also be changed by specifying
\fB\-mode\fR, but mode\-specific parameters associated with the account will be lost (e\&.g\&., the current counter value will be deleted if a
HOTP
account is changed to a
TOTP
account) and general parameters (such as the serial number) will be retained unless overridden on the command line\&.
.RE
.PP
\fB\-sync \fR\fB\fIpassword\-list\fR\fR
.RS 4
In
HOTP
mode, this attempts to synchronize the server with the token for
\fIusername\fR\&. The
\fIpassword\-list\fR
is a comma\-separated list of three successive passwords produced by the user\*(Aqs token (this "auto\-synchronize" function is also available through
\m[blue]\fBlocal_token_authenticate\fR\m[]\&\s-2\u[3]\d\s+2)\&. The given sequence must match the computed sequence
\fIexactly\fR, given the operational parameters in effect; e\&.g\&., leading zeroes are significant, as is the display radix and number of
OTP
digits in effect\&. If synchronization is successful, the user should be able to authenticate using the next password produced by the device\&. An exhaustive search algorithm using increasing counter values is employed, with a compile\-time limit on the maximum number of computations\&. The search begins at the server\*(Aqs currently stored counter value, unless one is provided using
\fB\-counter\fR\&. If unsuccessful, this operation could take a long time before it terminates; the user must contact an administrator for assistance\&.
.sp
In
TOTP
mode, attempt to determine how closely synchronized the system clock is with the token\*(Aqs clock and display the result\&. This information can be used to update the user\*(Aqs token record to compensate for poorly synchronized clocks, or to adjust validation parameters\&. The token\*(Aqs key and the name of the digest algorithm are obtained for the token record belonging to
\fIusername\fR, if it is given; otherwise the key is prompted for and the digest algorithm to use is either obtained from the command line or the default\&. Only the first password in
\fIpassword\-list\fR
is used\&. The
\fB\-totp\-timestep\fR,
\fB\-digits\fR, and
\fB\-totp\-base\fR
options are effective during this operation\&.
.RE
.PP
\fB\-test\fR
.RS 4
Perform some self\-tests, then exit\&. A non\-zero exit status means an error occurred\&.
.RE
.PP
\fB\-totp\-show\fR \fInum\fR
.RS 4
Display a sequence of
TOTP
passwords using the parameters currently in effect: interval size (\fB\-totp\-timestep\fR), number of digits (\fB\-digits\fR), and base (\fB\-base\fR)\&. The account\*(Aqs stored parameters are not modified\&. This is mainly intended for debugging purposes\&.
.sp
If a
\fIusername\fR
is provided (it must be associated with a
TOTP
device), the key and other stored parameters from the account are used unless overridden by command line flags\&. The sequence of passwords for
\fInum\fR
intervals before and after the current time, together with the password for the current time are printed\&.
.sp
If no
\fIusername\fR
is given, the program prompts for the key (which is echoed) if none has been provided, and uses command line flags or default values for parameters\&. It then emits the
TOTP
password for the current time each time
Return/Enter
is pressed; typing
EOF
causes immediate termination\&. If
\fInum\fR
is zero, however, the program does not wait for user input and prints only one password\&.
.RE
.PP
\fB\-validate\fR \fIotp\-value\fR
.RS 4
If
\fIotp\-value\fR
is the next expected one\-time password, return an exit status of zero to indicate success; any other value indicates failure\&. If
\fIusername\fR
is given, parameters for validation, including the key, are obtained from that account unless overridden on the command line\&. The server\*(Aqs state is not changed; e\&.g\&., a
HOTP
counter is not advanced\&. If no
\fIusername\fR
is given, the
\fB\-mode\fR
flag must be used and the parameters required for that mode must be given, including a key\&. For
HOTP
mode, a counter value must be provided\&. For
TOTP
mode, command line parameters are effective during this validation\&.
\fBdacstoken\fR
will test whether
\fIotp\-value\fR
validates against the parameters in effect\&.
.RE
.PP
The following
\fImodifier\fR
flags are understood:
.PP
.PP
\fB\-all\fR
.RS 4
With
\fB\-set\fR
and no
\fIusername\fR, apply the changes to
\fIall\fR
accounts\&. This can be used to enable or disable all accounts, for example\&. The
\fB\-inkeys\fR
and
\fB\-outkeys\fR
flags are honoured\&. If an error occurs processing stops immediately, in which case only some accounts may have been modified\&.
.RE
.PP
\fB\-base\fR \fInum\fR
.RS 4
Use
\fInum\fR
as the base (radix) when displaying an
OTP\&. The value of
\fInum\fR
is restricted to
\fB10\fR
(the default),
\fB16\fR, or
\fB32\fR\&.
.RE
.PP
\fB\-counter\fR \fInum\fR
.RS 4
This is the 8\-byte
HOTP
counter value to set, expressed as a hex value if preceded by by "0x" (or "0X"), decimal otherwise\&. Leading zeroes may be elided\&. This implies
HOTP
mode\&. For token devices, it should not be possible to reset a counter (modulo counter overflow) because that will result in the password sequence being repeated, assuming that the key is not changed; software implementations might not have this restriction, however, so beware of the security implications\&.
.RE
.PP
\fB\-digits\fR \fInum\fR
.RS 4
Use
\fInum\fR
digits when displaying an
OTP\&. The value of
\fInum\fR
is restricted to
\fB6\fR,
\fB7\fR,
\fB8\fR
(the default), or
\fB9\fR
with base
\fB10\fR\&. It is restricted to
\fB6\fR
with base
\fB32\fR
and is ignored with base
\fB16\fR
(hex output)\&.
.RE
.PP
\fB\-disable\fR
.RS 4
Disable the account for
\fIusername\fR\&. The
\fBlocal_token_authenticate\fR
module, and
\fB\-auth\fR
and
\fB\-validate\fR
flags, will not allow the user to authenticate until the account has been enabled, although other operations may still be performed on the account\&. If
\fB\-enable\fR
is subsequently used, the account will become usable for authentication and is restored to its state at the time it was disabled\&. It is not an error to disable an already disabled account\&.
.RE
.PP
\fB\-enable\fR
.RS 4
Enable the account for
\fIusername\fR\&. The
\fBlocal_token_authenticate\fR
module will allow the user to authenticate\&. It is not an error to enable an already enabled account\&.
.RE
.PP
\fB\-hotp\-window\fR \fInum\fR
.RS 4
If the expected
HOTP
password does not match the given password, try to match up to
\fInum\fR
passwords after the expected password in the sequence\&. A value of zero for
\fInum\fR
disables this search\&.
.RE
.PP
\fB\-ignore\-key\-length\fR
.RS 4
Do not enforce the minimum key length requirement (in bytes, applied to the decoded
\fIkeyval\fR
string argument specified by
\fB\-key\fR)\&.
.RE
.PP
\fB\-inkeys \fR\fB\fIitem_type\fR\fR
.RS 4
For decrypting secret keys, use the store identified by
\fIitem_type\fR, presumably configured in
dacs\&.conf\&.
.RE
.PP
\fB\-key\fR \fIkeyval\fR
.RS 4
Use
\fIkeyval\fR
as the secret key, expressed as a hex digit string by default (see
\fB\-key\-enc\fR)\&.
.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
Supplying a key on the command line is not secure because it may be visible to other processes\&.
.sp .5v
.RE
.RE
.PP
\fB\-key\-enc\fR \fIenc\fR
.RS 4
The secret key, however it is read by
\fBdacstoken\fR, has been encoded using algorithm
\fIenc\fR\&. Recognized values (case insensitive) for
\fIenc\fR
are "hex", "base32" (\m[blue]\fBRFC 4648\fR\m[]\&\s-2\u[45]\d\s+2), and "none" (plaintext)\&. The default is "hex"\&.
.RE
.PP
\fB\-key\-file\fR \fIfilename\fR
.RS 4
Read the secret key from
\fIfilename\fR, expressed as a hex digit string by default (see
\fB\-key\-enc\fR)\&. If
\fIfilename\fR
is "\-", the key is read from
stdin\&.
.RE
.PP
\fB\-key\-prompt\fR
.RS 4
Prompt for the secret key, expressed as a hex digit string by default (see
\fB\-key\-enc\fR)\&. The input is not echoed\&.
.RE
.PP
\fB\-mode\fR \fIotp\-mode\fR
.RS 4
This specifies (case insensitively) the type of token (the
OTP
device mode) for use with
\fB\-set\fR,
\fB\-create\fR, listing accounts, and validation and synchronization operations\&. The
\fIotp\-mode\fR
may be either
counter
or
hotp
for counter mode, or
time
or
totp
for time\-based mode, case insensitively\&. This flag is required when creating a new account\&.
.RE
.PP
\fB\-nl\fR
.RS 4
When exporting the
uri
format, suppress the newline\&. When generating a QR barcode from the
URI, a newline should not be encoded\&.
.RE
.PP
\fB\-outkeys \fR\fB\fIitem_type\fR\fR
.RS 4
For encrypting secret keys, use the store identified by
\fIitem_type\fR, presumably defined in
dacs\&.conf\&.
.RE
.PP
\fB\-pin\fR \fIpinval\fR
.RS 4
Use
\fIpinval\fR
as the secret
PIN
for the account\&.
.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
Supplying a
PIN
on the command line is not secure because it may be visible to other processes\&.
.sp .5v
.RE
.RE
.PP
\fB\-pin\-constraints\fR \fIstr\fR
.RS 4
Instead of using
\m[blue]\fBPASSWORD_CONSTRAINTS\fR\m[]\&\s-2\u[14]\d\s+2, use
\fIstr\fR
(having the same syntax and semantics) to describe the requirements for a
PIN\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
Requirements for a
PIN
apply to
PINs
obtained via a command line flag and to those obtained through importing (using the "p" attribute)\&. Requirements are not "retroactive", however, so changing the requirements does not affect the
PINs
of existing accounts or importing accounts that were previously exported (having a "ph" attribute)\&.
.sp .5v
.RE
.RE
.PP
\fB\-pin\-file\fR \fIfilename\fR
.RS 4
Read the secret
PIN
from
\fIfilename\fR\&. If
\fIfilename\fR
is "\-", the
PIN
is read from
stdin\&.
.RE
.PP
\fB\-pin\-prompt\fR
.RS 4
Prompt for the secret
PIN\&. The input is not echoed\&.
.RE
.PP
\fB\-rnd\fR
.RS 4
Reserved for future use\&.
.RE
.PP
\fB\-seed\fR \fIstr\fR
.RS 4
Reserved for future use\&.
.RE
.PP
\fB\-serial \fR\fB\fIstr\fR\fR
.RS 4
The serial number,
\fIstr\fR, is a (purportedly) unique identifier assigned to the token\&. This option is used with the
\fB\-set\fR,
\fB\-create\fR, and
\fB\-list\fR
flags\&. A serial number identifies a specific
OTP
device and need not be kept secret\&. The uniqueness property is enforced within an item type storage unit; that is, serial numbers of all
HOTP
devices must be unique, serial numbers of all
TOTP
devices must be unique, and if accounts for the two device types are combined, all device serial numbers must be unique\&. Any printable string is accepted\&. If a software client is generating passwords, you may use the device\*(Aqs serial number, or choose any suitably descriptive string not already assigned to a device\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
A jurisdiction that allows (or may eventually allow) both hardware tokens and software\-generating client applications should consider adopting a formalized naming scheme for its tokens\&. For example, the administrator might append "\-hw" to the vendor\*(Aqs serial number to form the
\fBdacstoken\fR
serial number\&. For software tokens, the administrator might create a
\fBdacstoken\fR
serial number by appending "\-sw" to the vendor\*(Aqs serial number for the device\&.
.sp .5v
.RE
.RE
.PP
\fB\-totp\-delta\fR \fInum\fR
.RS 4
Adjust the base time by
\fInum\fR
intervals (each of the step size number of seconds) when computing a
TOTP\&. The
\fInum\fR
may be negative, zero, or positive\&. This is used to correct for inadequately synchronized clocks\&.
.RE
.PP
\fB\-totp\-drift\fR \fInwindows\fR
.RS 4
For
TOTP, use a window size of
\fInwindows\fR
(in terms of the interval size) for validation\&. If
\fInwindows\fR
is
\fB0\fR, the computed
TOTP
value must match the given one exactly\&. If
\fInwindows\fR
is
\fB1\fR, for example,
\fBdacstoken\fR
will try to match the given
TOTP
value in the previous, current, and next intervals\&. This allows the clocks in the system running
\fBdacstoken\fR
(or
\fBlocal_token_authenticate\fR) and token producing device to be less well synchronized\&.
.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
Although it compensates for poorly synchronized clocks, increasing the value of
\fInwindows\fR
weakens the system by extending the lifetime of a one\-time password\&.
.sp .5v
.RE
.RE
.PP
\fB\-totp\-hash\fR \fIalg\fR
.RS 4
Use
\fIalg\fR
as the digest algorithm with
TOTP\&. The value of
\fIalg\fR
is restricted to
SHA1
(the default),
SHA256, or
SHA512\&. Digest name matching is described in
\m[blue]\fBdacs\&.exprs(5)\fR\m[]\&\s-2\u[46]\d\s+2\&.
.RE
.PP
\fB\-totp\-time\fR \fIsecs\fR
.RS 4
Use
\fIsecs\fR, expressed as the number of seconds since the Unix Epoch, instead of the current date and time\&.
.RE
.PP
\fB\-totp\-timestep\fR \fIsecs\fR
.RS 4
Use
\fIsecs\fR
as the interval size when computing a
TOTP\&. It must be greater than zero\&. The default is
\fB30\fR
seconds\&.
.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
Although it compensates for poorly synchronized clocks, increasing the value of
\fIsecs\fR
weakens the system by extending the lifetime of a one\-time password\&.
.sp .5v
.RE
.RE
.PP
\fB\-vfs\fR \fIvfs_uri\fR
.RS 4
Use
\fIvfs_uri\fR
to override the
\m[blue]\fBVFS\fR\m[]\&\s-2\u[23]\d\s+2
configuration directive in effect\&. This can be used to configure or reconfigure
auth_token,
auth_hotp_token, or
auth_totp_token
to specify the storage method for the accounts being acted upon\&.
.RE
.PP
Apart from error messages, which are printed to the standard error, all output goes to the standard output\&.
.PP
Ordinarily, a
\fIdacsoption\fR
will be specified to select the jurisdiction on behalf of which accounts are being managed\&.
.SH "EXAMPLES"
.PP
These examples assume that the jurisdiction name to use is
EXAMPLE
and its federation domain is
example\&.com\&.
.PP
To use this authentication method, a
\fBDACS\fR
administrator might perform the following steps for each
OTP
device assigned to a user:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  1." 4.2
.\}
Obtain a supported token or software client, review how it is used for authentication, and select values for the various parameters\&. For a hardware device, obtain the secret key from the vendor, or if it is programmable, select a suitable random key and program it into the device\&. For the
HOTP
algorithm, note the initial counter value; it might also be obtained from the vendor, although it is likely to initialized to zero\&. For a programmable device or client, set the initial counter value to zero\&. Decide whether a
PIN
will be required (see
\m[blue]\fBTOKEN_REQUIRES_PIN\fR\m[]\&\s-2\u[9]\d\s+2)\&.
.sp
If a software client is being used, install the software on the user\*(Aqs device (or have the user do so), and configure the software\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  2." 4.2
.\}
Decide where the account information will be stored for
\fBDACS\fR
and, if necessary, add a suitable
\m[blue]\fBVFS\fR\m[]\&\s-2\u[23]\d\s+2
directive to
dacs\&.conf\&. The default (found in
site\&.conf) maintains the account information in a file named
auth_tokens
within each jurisdiction\*(Aqs default private area:
.sp
.if n \{\
.RS 4
.\}
.nf
VFS "[auth_token]dacs\-kwv\-fs:${Conf::FEDERATIONS_ROOT}/\e
${Conf::FEDERATION_DOMAIN}/${Conf::JURISDICTION_NAME}/auth_tokens"
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  3." 4.2
.\}
Generate keys to encrypt the account information (see
\m[blue]\fBTokens and secret keys\fR\m[]\&\s-2\u[47]\d\s+2) and decide where they will be stored; for example (your user ID, group ID, path, jurisdiction name, and federation domain may vary):
.sp
.if n \{\
.RS 4
.\}
.nf
% cd /usr/local/dacs/federations_root/example\&.com/EXAMPLE
% dacskey \-uj EXAMPLE \-q auth_token_keys
% chgrp www auth_token_keys
% chmod 0640 auth_token_keys
.fi
.if n \{\
.RE
.\}
.sp
If necessary, add a suitable
\m[blue]\fBVFS\fR\m[]\&\s-2\u[23]\d\s+2
directive to
dacs\&.conf; the default, which is used above, maintains the account information in a file named
auth_token_keys
within each jurisdiction\*(Aqs default private area:
.sp
.if n \{\
.RS 4
.\}
.nf
VFS "[auth_token_keys]dacs\-fs:${Conf::FEDERATIONS_ROOT}/\e
${Conf::FEDERATION_DOMAIN}/${Conf::JURISDICTION_NAME}/auth_token_keys"
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  4." 4.2
.\}
If you need users to sign on through
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[2]\d\s+2, you must configure a suitable
Auth
clause in
dacs\&.conf, for example:
.sp
.if n \{\
.RS 4
.\}
.nf
<Auth id="token">
  URL "token"
  STYLE "pass"
  CONTROL "sufficient"
</Auth>
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 5.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  5." 4.2
.\}
There are several ways that an administrator might proceed, depending on how much of the effort can be done by users (e\&.g\&., whether they can be trusted, their technical ability), how many users there are (a few, or thousands), and the level of security required\&. Here is one way:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  1." 4.2
.\}
prepare a file containing an
\m[blue]\fBXML record\fR\m[]\&\s-2\u[48]\d\s+2
for each account to be created; if
PINs
are to be used, assign a random
PIN
to each account;
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  2." 4.2
.\}
use the
\m[blue]\fB\-import\fR\m[]\&\s-2\u[49]\d\s+2
flag to create the accounts;
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  3." 4.2
.\}
give the token device, username, and (if necessary) initial
PIN
to the user (perhaps verifying identity), providing any necessary demonstration and instructions;
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  4." 4.2
.\}
have the user set or reset the
PIN
for the account, and ask the user to sign on using the token to confirm correct operation\&.
.RE
.sp
Another method of provisioning a token\-based account using a QR barcode might follow steps similar to these for user
alice:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  1." 4.2
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
% dacstoken \-format uri \-export \-issuer DSS \-nl alice > alice\&.uri
% qrencode \-o alice\&.png < alice\&.uri
% chmod 0600 alice\&.uri alice\&.png
.fi
.if n \{\
.RE
.\}
.sp
The exported
URI
put in
alice\&.uri
might look something like this:
.sp
.if n \{\
.RS 4
.\}
.nf
otpauth://totp/DSS:alice?secret=NBSWY3DPFR3W64TMMQXGCYTDMRSQ&issuer=DSS&algorithm=SHA1&digits=8&period=30
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  2." 4.2
.\}
The image file
alice\&.png
is then sent to Alice over a sufficiently secure channel, after which
alice\&.png
and
alice\&.uri
may be deleted\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  3." 4.2
.\}
Upon obtaining
alice\&.png, Alice scans or imports the
URI
using her
OTP
client\&. If the user has a web browser that has been configured to associate the
otpauth
URI
scheme with a suitable
OTP
client, it may be possible for the user to initialize the new account using the
URI
directly rather than the equivalent QR barcode\&. Her client should now be capable of generating a password stream that is synchronized with her
\fBDACS\fR
token account\&. If
HOTP
is being used, several
OTP
values might be provided with
alice\&.png
so that Alice can verify that her client has correctly initialized her account\&.
.sp
.if n \{\
.RS 4
.\}
.nf
% dacstoken \-hotp\-show 3 alice
0000000000000000: 070440
0000000000000001: 089277
0000000000000002: 253240
.fi
.if n \{\
.RE
.\}
.sp
Alternatively, a web page might be provided to help users verify correct operation and enable their account\&.
.RE
.sp
.RE
.PP
To create a disabled account for user
bobo
for a
HOTP
device:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacstoken \-uj EXAMPLE \-mode hotp \-serial 37000752 \-key\-file bobo\&.key \-create bobo
.fi
.if n \{\
.RE
.\}
.sp
In this example, the secret key for the account (which must not already exist) is read from the file
bobo\&.key\&. New accounts are disabled by default\&. Use
\fB\-enable\fR
to create an enabled account\&.
.PP
Once an account has been created, it can be synchronized with the token\&. To synchronize the
HOTP
token for user
bobo:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacstoken \-uj EXAMPLE \-sync 433268,894121,615120 bobo
.fi
.if n \{\
.RE
.\}
.sp
In this example, the particular token produced the three consecutive passwords
433268,
894121, and
615120\&. Note that the password sequence string that follows the
\fB\-sync\fR
flag is a single argument that cannot have any embedded spaces\&. If the key for this token is the value
19c0a3519a89b4a8034c5b9306db, supplied as a hex string, the next password generated by this token should be
544323
(with counter value
\fB13\fR)\&. This can be verified using
\fB\-hotp\-show\fR:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacstoken \-hotp\-show 5 \-counter 10 \-key 19c0a3519a89b4a8034c5b9306db \-ignore\-key\-length
000000000000000a: 433268
000000000000000b: 894121
000000000000000c: 615120
000000000000000d: 544323
000000000000000e: 002442
.fi
.if n \{\
.RE
.\}
.PP
To enable the account for user
bobo:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacstoken \-uj EXAMPLE \-enable \-set bobo
.fi
.if n \{\
.RE
.\}
.PP
To both set the
PIN
and enable the account for user
bobo:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacstoken \-uj EXAMPLE \-enable \-pin "CzAy" \-set bobo
.fi
.if n \{\
.RE
.\}
.PP
To list all accounts in detail:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacstoken \-uj EXAMPLE \-long
.fi
.if n \{\
.RE
.\}
.sp
The
\fB\-list\fR
flag is redundant because it is the default operation\&. The
\fB\-counter\fR, etc\&. modifiers have no effect when listing\&.
.PP
To list only the account for
bobo:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacstoken \-uj EXAMPLE \-list bobo
.fi
.if n \{\
.RE
.\}
.sp
The exit status will be non\-zero if this user does not have an account\&.
.PP
To display the account for the device with serial number
37000752:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacstoken \-uj EXAMPLE \-serial 37000752
.fi
.if n \{\
.RE
.\}
.sp
The serial number, which should uniquely identify a token, is often printed on the token or can be displayed by the token\&.
.PP
To set the counter value for the existing account of
bobo:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacstoken \-uj EXAMPLE \-counter 9 \-set bobo
.fi
.if n \{\
.RE
.\}
.sp
This operation might be used for testing or with a software token\&. The
\fB\-sync\fR
operation is better suited to a hardware token\&.
.PP
To change the
PIN
for username
bobo:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacstoken \-uj EXAMPLE \-pin\-prompt \-set bobo
.fi
.if n \{\
.RE
.\}
.sp
The program will prompt for the new
PIN\&.
.PP
To use an alternate account file,
/secure/auth_tokens:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacstoken \-uj EXAMPLE \-vfs "dacs\-kwv\-fs:/secure/auth_tokens" \-list
.fi
.if n \{\
.RE
.\}
.PP
To use new keys (making the same assumptions as earlier), add a suitable
VFS
directive to
dacs\&.conf; the default defines the item type
auth_token_keys_prev
as follows:
.sp
.if n \{\
.RS 4
.\}
.nf
VFS "[auth_token_keys_prev]dacs\-fs:${Conf::FEDERATIONS_ROOT}/\e
${Conf::FEDERATION_DOMAIN}/${Conf::JURISDICTION_NAME}/auth_token_keys\&.prev"
.fi
.if n \{\
.RE
.\}
.sp

.sp
.if n \{\
.RS 4
.\}
.nf
% cd /usr/local/dacs/federations_root/example\&.com/EXAMPLE
% mv auth_token_keys auth_token_keys\&.prev
% dacskey \-uj EXAMPLE \-q auth_token_keys
% chgrp www auth_token_keys
% chmod 0640 auth_token_keys
% dacstoken \-uj EXAMPLE \-inkeys auth_token_keys\&.prev \-set
.fi
.if n \{\
.RE
.\}
.PP
The following examples outline how
\fBdacstoken\fR
might be used to generate the same output sequence as
\m[blue]\fBGoogle Authenticator\fR\m[]\&\s-2\u[50]\d\s+2
(tested with Version 2\&.1\&.0\&.2212)\&. Here, the key is "mfrggzdf", which is the
\m[blue]\fBbase\-32 encoding\fR\m[]\&\s-2\u[42]\d\s+2
of the string "abcde"\&. Since this an unsafe, five\-byte long key, it must be expressly allowed by using the
\fB\-ignore\-key_length\fR
flag\&. Google Authenticator produces codes composed of six decimal digits\&. In
HOTP
(counter\-based) mode, Google Authenticator starts a new token with a counter value of one\&. Using this command,
\fBdacstoken\fR
displays ten consecutive codes, starting with the code for a counter value of one:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacsexpr \-e \*(Aqencode(base32,"abcde")\*(Aq
"MFRGGZDF"
% dacstoken \-un \-hotp\-show 10 \-digits 6 \-counter 1 \-key mfrggzdf \-key\-enc base32 \-ignore\-key\-length
0000000000000001: 106998
0000000000000002: 421654
0000000000000003: 118157
0000000000000004: 283104
0000000000000005: 848242
0000000000000006: 615855
0000000000000007: 507768
0000000000000008: 063257
0000000000000009: 974271
000000000000000a: 178655
.fi
.if n \{\
.RE
.\}
.sp
Similarly, for
TOTP
(time\-based) mode, this displays the current time\-based code that should match the code produced by Google Authenticator during the same time interval (if you try this your output code will most likely be different):
.sp
.if n \{\
.RS 4
.\}
.nf
% dacstoken \-un \-totp\-show 0 \-digits 6 \-key mfrggzdf \-key\-enc base32 \-ignore\-key\-length
TOTP=525711 [at t=1371760542]
.fi
.if n \{\
.RE
.\}
.PP
To generate some of the
\m[blue]\fBRFC 6238\fR\m[]\&\s-2\u[5]\d\s+2, Appendix B test vector values:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacstoken \-un \-totp\-show 0 \-key 12345678901234567890 \-key\-enc none \-totp\-time 59
TOTP=94287082 [at t=59]
% dacstoken \-un \-totp\-show 0 \-key 12345678901234567890123456789012 \-totp\-hash sha256 \-key\-enc none \-totp\-time 59
TOTP=46119246 [at t=59]
% dacstoken \-un \-totp\-show 0 \-key 1234567890123456789012345678901234567890123456789012345678901234 \e
  \-totp\-hash sha512 \-key\-enc none \-totp\-time 59
TOTP=90693936 [at t=59]
% dacstoken \-un \-totp\-show 0 \-key 12345678901234567890 \-key\-enc none \-totp\-time 2000000000
TOTP=69279037 [at t=2000000000]
.fi
.if n \{\
.RE
.\}
.PP
The
\m[blue]\fBdacsexpr(1)\fR\m[]\&\s-2\u[18]\d\s+2
\m[blue]\fBbase\-32 encoding and decoding functions\fR\m[]\&\s-2\u[51]\d\s+2
may be helpful\&.
.SH "DIAGNOSTICS"
.PP
The program exits
0, or
1
if an error occurred\&.
.SH "BUGS"
.PP
HOTP
should probably be called
COTP, but
HOTP
came before
TOTP\&.
WOTP?
.PP
Listings may only be sorted by username\&.
.PP
The drift adjustment for
TOTP
accounts is tied to the real time clocks of a particular client/server pair\&. If either clock is effectively changed "too much" (e\&.g\&., by resetting a very fast server clock or replacing an old token that had a relatively slower clock), then a user will observe the token to suddenly stop working\&. Resynchronization is required in these cases\&. Sharing an account file amongst two or more servers should be avoided in general (because locks are unlikely to be visible across hosts), but also if their clocks are not always well synchronized\&. It is recommended that the Network Time Protocol (\m[blue]\fBRFC 1305\fR\m[]\&\s-2\u[52]\d\s+2) or equivalent be used on any host that runs
\fBDACS\fR
commands or web services\&.
.PP
The implementation of time\-based tokens was originally based on the Internet\-Draft available at the time (draft\-mraihi\-totp\-timebased\-05\&.txt) but is expected to conform to
\m[blue]\fBRFC 6238\fR\m[]\&\s-2\u[5]\d\s+2,
\fITOTP: Time\-Based One\-Time Password Algorithm\fR, and interoperate with other conformant hardware and software tokens\&.
\fBDACS\fR
passes both documents\*(Aq test vectors\&.
.PP
TOTP
password matching windows are symmetrical\&.
.PP
This functionality should probably be available through
\m[blue]\fBdacs_admin(8)\fR\m[]\&\s-2\u[53]\d\s+2
and
\m[blue]\fBdacsauth(1)\fR\m[]\&\s-2\u[54]\d\s+2, but it\*(Aqs not\&.
.PP
Mutual authentication using tokens should be implemented\&.
.PP
Although release
1\&.4\&.25
introduced many improvements, some cause incompatibilities with earlier versions of
\fBdacstoken\fR\&.
.PP
The shared secret keys used to generate one\-time passwords are protected on the server side by storing them in encrypted form\&. But since the decryption key must be readily accessible to
\fBDACS\fR
at run\-time for token generation, a server compromise could make it straightforward for an attacker to obtain both an account file and the symmetric key used to encrypt/decrypt secret keys unless appropriate steps are not taken\&. One idea is to involve the user\-provided
PIN
or password in the construction or encryption of the symmetric key\&. Also, all shared secret keys must be kept private on the client side\&.
.SH "SEE ALSO"
.PP
\m[blue]\fBRFC 4226\fR\m[]\&\s-2\u[4]\d\s+2,
\m[blue]\fBdraft\-mraihi\-totp\-timebased\-08\&.txt\fR\m[]\&\s-2\u[55]\d\s+2,
\m[blue]\fBRFC 6238\fR\m[]\&\s-2\u[5]\d\s+2,
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[2]\d\s+2,
\m[blue]\fBdacs_token(8)\fR\m[]\&\s-2\u[8]\d\s+2,
\m[blue]\fBdacsgrid(1)\fR\m[]\&\s-2\u[56]\d\s+2,
\m[blue]\fBdacspasswd(1)\fR\m[]\&\s-2\u[10]\d\s+2,
\m[blue]\fBopie(4)\fR\m[]\&\s-2\u[57]\d\s+2,
\m[blue]\fBMobile One Time Passwords\fR\m[]\&\s-2\u[58]\d\s+2,
\m[blue]\fBmod_authn_otp\fR\m[]\&\s-2\u[59]\d\s+2
.SH "AUTHOR"
.PP
Distributed Systems Software (\m[blue]\fBwww\&.dss\&.ca\fR\m[]\&\s-2\u[60]\d\s+2)
.SH "ACKNOWLEDGEMENTS"
.PP
Our sincere thanks to
\m[blue]\fBAuthenex, Inc\&.\fR\m[]\&\s-2\u[25]\d\s+2
and
\m[blue]\fBHyperSecu Information Systems, Inc\&.\fR\m[]\&\s-2\u[61]\d\s+2
for generously providing samples of their products and technical support\&.
.SH "COPYING"
.PP
Copyright \(co 2003\-2018 Distributed Systems Software\&. See the
\m[blue]\fBLICENSE\fR\m[]\&\s-2\u[62]\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
dacs_authenticate
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html
.RE
.IP " 3." 4
local_token_authenticate
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html#token
.RE
.IP " 4." 4
RFC 4226
.RS 4
\%http://www.rfc-editor.org/rfc/rfc4226.txt
.RE
.IP " 5." 4
RFC 6238
.RS 4
\%http://www.rfc-editor.org/rfc/rfc6238.txt
.RE
.IP " 6." 4
RFC 6287
.RS 4
\%http://www.rfc-editor.org/rfc/rfc6287.txt
.RE
.IP " 7." 4
\fB-convert\fR flag
.RS 4
\%http://dacs.dss.ca/man/#convert_flag
.RE
.IP " 8." 4
dacs_token(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_token.8.html
.RE
.IP " 9." 4
TOKEN_REQUIRES_PIN
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#TOKEN_REQUIRES_PIN
.RE
.IP "10." 4
dacspasswd(1)
.RS 4
\%http://dacs.dss.ca/man/dacspasswd.1.html
.RE
.IP "11." 4
dacs_passwd(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_passwd.8.html
.RE
.IP "12." 4
PASSWORD_DIGEST
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#PASSWORD_DIGEST
.RE
.IP "13." 4
PASSWORD_SALT_PREFIX
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#PASSWORD_SALT_PREFIX
.RE
.IP "14." 4
PASSWORD_CONSTRAINTS
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#PASSWORD_CONSTRAINTS
.RE
.IP "15." 4
RFC 2104
.RS 4
\%http://www.rfc-editor.org/rfc/rfc2104.txt
.RE
.IP "16." 4
FIPS 198
.RS 4
\%http://csrc.nist.gov/publications/fips/fips198/fips-198a.pdf
.RE
.IP "17." 4
time(3)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=time&apropos=0&sektion=3&manpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP "18." 4
dacsexpr(1)
.RS 4
\%http://dacs.dss.ca/man/dacsexpr.1.html
.RE
.IP "19." 4
man-in-the-middle attack
.RS 4
\%http://en.wikipedia.org/wiki/Man-in-the-middle_attack
.RE
.IP "20." 4
revocation list
.RS 4
\%http://dacs.dss.ca/man/dacs.acls.5.html#revocation_list
.RE
.IP "21." 4
local_passwd_authenticate
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html#passwd
.RE
.IP "22." 4
\fBDACS\fR identities
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html#gloss_identity
.RE
.IP "23." 4
VFS
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#VFS
.RE
.IP "24." 4
dacskey(1)
.RS 4
\%http://dacs.dss.ca/man/dacskey.1.html
.RE
.IP "25." 4
Authenex A-Key\(rg 3600
.RS 4
\%http://www.authenex.com
.RE
.IP "26." 4
Feitian Technologies
.RS 4
\%https://www.ftsafe.com/
.RE
.IP "27." 4
HyperSecu Information Systems
.RS 4
\%https://www.hypersecu.com
.RE
.IP "28." 4
Google Authenticator
.RS 4
\%https://itunes.apple.com/ca/app/google-authenticator/id388497605
.RE
.IP "29." 4
open source
.RS 4
\%https://fedorahosted.org/freeotp
.RE
.IP "30." 4
FreeOTP Authenticator
.RS 4
\%https://itunes.apple.com/ca/app/freeotp-authenticator/id872559395
.RE
.IP "31." 4
Red Hat
.RS 4
\%https://www.redhat.com
.RE
.IP "32." 4
OATH Token
.RS 4
\%https://github.com/archiecobbs/oathtoken
.RE
.IP "33." 4
iPod Touch, iPhone, and iPad
.RS 4
\%http://itunes.apple.com/us/app/oath-token/id364017137
.RE
.IP "34." 4
OTP Auth
.RS 4
\%https://itunes.apple.com/ca/app/otp-auth/id659877384
.RE
.IP "35." 4
contact
.RS 4
\%http://www.dss.ca/contactus.html
.RE
.IP "36." 4
Photo
.RS 4
\%http://dacs.dss.ca/otp-tokens2.jpg
.RE
.IP "37." 4
KeyUriFormat
.RS 4
\%https://github.com/google/google-authenticator/wiki/Key-Uri-Format
.RE
.IP "38." 4
\fIdacsoptions\fR
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html#format-arg
.RE
.IP "39." 4
QR Code
.RS 4
\%http://en.wikipedia.org/wiki/QR_code
.RE
.IP "40." 4
ZBar
.RS 4
\%http://zbar.sourceforge.net
.RE
.IP "41." 4
libqrencode library
.RS 4
\%http://fukuchi.org/works/qrencode/
.RE
.IP "42." 4
base-32 encoded
.RS 4
\%https://en.wikipedia.org/wiki/Base32
.RE
.IP "43." 4
\fB-validate\fR
.RS 4
\%http://dacs.dss.ca/man/#validate_flag
.RE
.IP "44." 4
\fB-set\fR
.RS 4
\%http://dacs.dss.ca/man/#set_flag
.RE
.IP "45." 4
RFC 4648
.RS 4
\%http://www.rfc-editor.org/rfc/rfc4648.txt
.RE
.IP "46." 4
dacs.exprs(5)
.RS 4
\%http://dacs.dss.ca/man/dacs.exprs.5.html#digest
.RE
.IP "47." 4
Tokens and secret keys
.RS 4
\%http://dacs.dss.ca/man/#security1
.RE
.IP "48." 4
XML record
.RS 4
\%http://dacs.dss.ca/man/#user_provisioning
.RE
.IP "49." 4
-import
.RS 4
\%http://dacs.dss.ca/man/#import_flag
.RE
.IP "50." 4
Google Authenticator
.RS 4
\%http://en.wikipedia.org/wiki/Google_Authenticator
.RE
.IP "51." 4
base-32 encoding and decoding functions
.RS 4
\%http://dacs.dss.ca/man/dacs.exprs.5.html#encode
.RE
.IP "52." 4
RFC 1305
.RS 4
\%http://www.rfc-editor.org/rfc/rfc1305.txt
.RE
.IP "53." 4
dacs_admin(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_admin.8.html
.RE
.IP "54." 4
dacsauth(1)
.RS 4
\%http://dacs.dss.ca/man/dacsauth.1.html
.RE
.IP "55." 4
draft-mraihi-totp-timebased-08.txt
.RS 4
\%https://tools.ietf.org/id/draft-mraihi-totp-timebased-08.txt
.RE
.IP "56." 4
dacsgrid(1)
.RS 4
\%http://dacs.dss.ca/man/dacsgrid.1.html
.RE
.IP "57." 4
opie(4)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=opie&apropos=0&sektion=4&manpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP "58." 4
Mobile One Time Passwords
.RS 4
\%http://motp.sourceforge.net
.RE
.IP "59." 4
mod_authn_otp
.RS 4
\%https://github.com/archiecobbs/mod-authn-otp
.RE
.IP "60." 4
www.dss.ca
.RS 4
\%http://www.dss.ca
.RE
.IP "61." 4
HyperSecu Information Systems, Inc.
.RS 4
\%https://www.hypersecu.com/
.RE
.IP "62." 4
LICENSE
.RS 4
\%http://dacs.dss.ca/man/../misc/LICENSE
.RE