Provided by: dacs_1.4.28b-3ubuntu2_amd64 
NAME
dacstoken - administer hash-based one-time passwords
SYNOPSIS
dacstoken [dacsoptions[1]] [-all] [-base num] [-counter num] [-digits num]
[-disable | -enable] [-hotp-window num] [-inkeys item_type]
[[-key keyval] | [-key-file filename] | [-key-prompt]] [-mode otp-mode]
[-outkeys item_type]
[[-pin pinval] | [-pin-file filename] | [-pin-prompt]] [-pin-constraints str]
[-rnd] [-seed str] [-serial str] [-totp-delta num] [-totp-drift nwindows]
[-totp-hash alg]
[-totp-timestep secs] [-vfs vfs_uri] [op-spec] [username]
DESCRIPTION
This program is part of the DACS suite.
The dacstoken utility administers DACS accounts associated with one-time password (OTP)
generating devices (tokens) 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.
Strong, two-factor authentication can be provided when dacs_authenticate[2] is configured
to use the local_token_authenticate[3] authentication module or when dacstoken is used as
a standalone program to validate passwords. Both the HMAC-based one-time password mode
(HOTP), based on an event counter and specified by RFC 4226[4], and the time-based
one-time password mode (TOTP), as specified by the latest IETF Internet-Draft[5] proposal,
are supported. Additional operational modes[6] called OCRA (OATH Challenge-Response
Algorithms), described in an IETF Internet-Draft, are not yet fully supported.
Note
This version of dacstoken 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 -convert flag[7] in particular).
Important
No vendor-supplied software is required by dacstoken to supply its functionality. The
devices currently supported do not need any registration or configuration interaction
with vendors and dacstoken does not interact with vendors' servers or use any
proprietary software. Vendor-supplied software may be required to perform
initialization or configuration for other token devices, however, and dacstoken does
not provide such support for them.
Each token device generally corresponds to exactly one account that is managed by
dacstoken, although some vendors produce tokens that can support multiple accounts.
To summarize, this utility:
• creates and administers DACS accounts associated with counter-based and time-based
one-time passwords
• provides validation and testing functionality
• provides a command line authentication capability
Security
Only the DACS administrator should be able to successfully run this program from the
command line. Because DACS 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.
Note
The dacs_token(8)[8] 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.
PINs (Account Passwords)
A dacstoken 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 and the PIN. The TOKEN_REQUIRES_PIN[9] configuration directive determines
whether a PIN must be provided when creating or importing an account; it does not apply in
conjunction with the -delpin flag, since only an administrator should be able to perform
that function.
A hash of the PIN is stored in the account record rather than the PIN itself. The same
method used by dacspasswd(1)[10] and dacs_passwd(8)[11] is applied, and depends on the
PASSWORD_DIGEST[12] and PASSWORD_SALT_PREFIX[13] directives in effect. If
PASSWORD_DIGEST[12] is configured, that algorithm is used, otherwise a compile-time
default (SHA1) 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.
Some token devices have a PIN capability built into them. 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 that is managed by dacstoken, and this manual is
only concerned with the dacstoken PIN. The device PIN should always be used when possible;
the dacstoken PIN is strongly recommended and is required for two-factor authentication
(unless an additional authentication factor is applied in some other way).
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
PASSWORD_CONSTRAINTS[14] directive.
One-Time Passwords
Both kinds of one-time password device compute a password value by employing a secure
keyed hash algorithm (RFC 2104[15], FIPS 198[16]). 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's matching algorithm will typically allow a client's 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 time(3)[17], 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's matching algorithm must also allow a client's
password to fall within some number of time-step windows for these devices.
Security
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's
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's 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.
If the secret key is programmable, as it is likely to be with a software client, it is
required to be at least 128 bits in length; a minimum of 160 bits is recommended. The
key is represented by a 16 (or more) character long hexadecimal string. The key 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 dacsexpr(1)[18]:
% dacsexpr -e "random(string, 20)"
"bb2504780e8075a49bd88891b228fc7216ac18d9"
Tip
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.
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' documentation for details.
base
The radix in which passwords are displayed.
counter
For HOTP mode only, the current counter value.
digits
The number of digits in each one-time password.
key
The secret key (OTP seed).
serial number
A unique identifier or name for the device.
time step size
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.
In addition to these parameters, dacstoken employs several per-account (i.e., per-device)
parameters:
accept-window
When validating a HOTP password, the maximum number of passwords to consider after the
expected password.
drift
For TOTP mode only, the number of seconds by which to adjust the server's 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's.
drift-window
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.
sync-otps
For HOTP mode only, the number of consecutive one-time passwords required to
synchronize the account with the device.
username
The name of the DACS account bound to the device.
Authentication based on one-time password devices has the following advantages:
• 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;
• 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;
• If no correction for clock drift is required, a TOTP mode account can have read-only
operation;
• Because the password is unlikely to be an easily-guessed number or string, it should
be stronger than most user-selected passwords;
• A HOTP token can be the basis of a mutual ("bidirectional") authentication method; the
server shows the user his token's 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;
• Should a key sniffer be installed on the user's computer, a sniffed password does not
do an attacker any good unless a man-in-the-middle attack[19] is possible; given N
consecutive passwords it is still very difficult to compute password N + 1 without
knowing the secret key;
• It is more difficult for users to share an account (although users might sometimes
view this as an inconvenience);
• If a dacstoken PIN is assigned to an account and an attacker obtains the account's
token, it is still difficult for the attacker to authenticate without knowing the PIN;
• 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 revocation list[20];
• 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).
One-time password devices have the following potential disadvantages:
• 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's battery (some units have a
non-replaceable battery, making them disposable after a few years);
• 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;
• 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;
• Users can forget to have their token with them or lose the token;
• 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);
• 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;
• Entering a 40 character or longer seed value into a mobile device can be frustrating
and prone to error;
• 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);
• Some devices are difficult to read in low-light conditions; presbyopic users and those
with impaired vision may have difficulty reading the display.
Accounts
The accounts managed by dacstoken are completely separate from the accounts used by
local_passwd_authenticate[21] or any other DACS authentication module.
Accounts for HOTP and TOTP devices may either be combined 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 DACS's 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 local_token_authenticate.
If accounts for the two device types are combined, 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 DACS 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 DACS 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.
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 DACS identities[22].
The -vfs is used to configure or reconfigure the auth_token item type.
Only keys that meet the minimum key length requirement (16 bytes) may be stored with
account information (e.g., with -set or -import). In other contexts, the requirement is
not enforced.
The secret key is encrypted by dacstoken when it is written to the account file. The
virtual filestore item type auth_token_keys identifies the encryption keys for dacstoken
to use; the -inkeys and -outkeys flags specify alternatives (see dacskey(1)[23]). If the
encryption keys are lost, the secret keys are practically unrecoverable.
Important
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.
Important
• This authentication method has been tested against the following OTP products:
• Authenex A-Key 3600[24] one-time password (HOTP) hardware token;
• Feitian Technologies[25] OTP C100 and OTP C200 one-time password hardware
tokens, provided by HyperSecu Information Systems[26]; and
• OATH Token[27] software application by Archie Cobbs, which implements both
HOTP and TOTP on the iPod Touch, iPhone, and iPad[28].
• Feitian Technologies iOATH Lite[29] HOTP software application for the iPod
Touch, iPhone, and iPad.
Other manufacturers interested in having their products supported by DACS are
welcome to contact Dss.
• Photo[30]: Feitian OTP C200, iPod Touch with the OATH Token app, Authenex A-Key
3600 (clockwise from top left)
• Although this implementation should work with similar, conformant products, only
these products are officially supported by DACS.
• Hardware tokens can be purchased directly from the vendors.
• Any problems with using tokens to authenticate through DACS are not the
responsibility of the token vendor.
Importing and Exporting OTP Accounts
Descriptions of accounts and their tokens can be loaded or dumped (refer to the -import
and -export flags). This simplifies bulk provisioning, backup, and portability. The
account information is written in a simple, application-specific (almost) XML format.
The format understood by dacstoken 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 SHA1. 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 ("'" and """,
respectively), as must the "<" (less than) and "&" (ampersand) characters. A ">" (greater
than) character may optionally be replaced by a ">" sequence, but no other entity
references are recognized.
Recognized attributes are:
• b:
base
-- radix for OTP value
[Optional:
10 (default),
16, or 32]
• c:
counter
-- current counter value for HOTP, in hex if preceded
by "0x" (or "0X"), decimal otherwise
[Optional:
default is 0]
• d:
OTP device mode
-- "c" (for HOTP)
or "t" (for TOTP)
[Required]
• dn:
digest-name
-- one of the Secure Hash Algorithms
[Optional:
SHA1 (default),
SHA224, SHA256,
SHA384, SHA512]
• dr:
clock-drift
-- clock adjustment, in seconds, for TOTP
[Optional]
• ek:
encrypted-key
-- encrypted secret key, base-64 encoded
[Required:
OTP account records only]
• en:
enabled-status
-- 1 for enabled,
0 for disabled
[Required]
• k:
plaintext-key
-- unencrypted secret key
[Required]
• lu:
last-update
-- Unix time of last record update
[Optional: default is current time]
• nd:
ndigits
-- number of digits for OTP value
[Optional:
default is 6 for HOTP,
8 for TOTP]
• p:
plaintext-PIN
-- plaintext PIN value for the account
[Required:
unless ph is present,
for import only]
• ph:
hashed-PIN
-- hashed PIN value for the account
[Optional:
generated by dacstoken
for export and OTP account files only]
• s:
serial-number
-- unique identifier string for the device
[Required]
• ts:
time-step
-- time-step value, in seconds, for TOTP
[Optional:
default is 30]
• u:
username
-- a valid DACS username associated with this account
[Required]
The following example describes two accounts that might be created using the -import flag:
<otp_tokens>
<!-- Staff OTP tokens for DACS authentication -->
<otp_token u="ietf" d="t" en="1" s="totp-ietf "draft"" 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>
Security
Because imported records include the unencrypted secret keys for the OTP devices, the
exported file should be kept encrypted (e.g., using openssl) or at least have
appropriate file permissions.
Note
A standard format for OTP device provisioning is being developed. This format may be
understood by a future version of dacstoken, or a conversion utility may be written.
The standard format is likely to be considerably more complex than the DACS format.
OPTIONS
In addition to the standard dacsoptions[1], a lengthy list of command line flags are
recognized. When a username 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., -counter, -totp-show) and their appearance implies that mode,
making the -mode flag unnecessary; other flags are mode independent (e.g., -delete,
-enable). 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.
The op-spec specifies the operation to be performed, together with zero or more modifier
flags. If op-spec is missing, the -list operation is performed. An op-spec is one of the
following:
-auth otp-value
This flag is like -validate[31], except:
• a username is required, from which all parameters are obtained (such as the key);
• if the account has a PIN, it must be provided;
• if the account is for a HOTP token, the counter will be updated if authentication
is successful.
An exit status of zero indicates successful authentication, while any other value
means authentication failed.
-convert filename
Load an older format (prior to release 1.4.25) token account file from filename ("-"
means to read from stdin), convert it to the newer format, and write it to stdout (as
by -export). This flag is deprecated and this capability will be removed in a future
release of DACS.
-create
Create an account for username, which must not already exist. In other respects it
works like -set[32]. When creating a new account, -serial is required and -key is
implied. If no -enable flag is provided when creating an account, -disable is implied.
If no -counter 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).
-current
Display the current moving factor (i.e., the counter value for HOTP or the interval
value for TOTP) and expected OTP for username. For HOTP, the counter is advanced. All
parameters are taken from the account.
-delete
Delete the account for username. The device's secret key and other operational
parameters will be lost.
-delpin
Delete the PIN, if present, on the account for username, leaving the account without a
PIN.
-export
Write information about all accounts, or only one account if username is given, to
stdout. If a mode is selected, however, only accounts having that mode will be
written. This information may be reloaded using -import or -import-replace. The output
should be stored in an encrypted form, or at the very least have its file permissions
set appropriately. For example:
% dacstoken -uj EXAMPLE -export | openssl enc -aes-256-cbc > dacstoken-exported.enc
Later, you might do something like:
% openssl enc -d -aes-256-cbc < dacstoken-exported.enc | dacstoken -uj EXAMPLE -import -
-h
-help
Display a help message and exit.
-hotp-show num
Display num consecutive HOTP passwords from a given counter value and key. The
-counter flag can be used to specify an initial counter value. The key can be
specified using -key, -key-file, or -key-prompt. If a username is provided, the
initial counter value and key are obtained from the user's HOTP account, unless either
value is overridden on the command line; the account's stored counter value is not
modified. This is mainly intended for debugging purposes.
-import filename
-import-replace filename
Load account and token information from filename; if filename is "-", stdin is read.
If a mode is selected, only accounts having that mode will be read. With -import it is
an error if an imported account already exists, and processing stops; -import-replace
will replace an existing account with imported data.
-l
-list
-long
If username is provided, display information about the corresponding account; if the
-serial flag is given, display information about the account with the specified serial
number; otherwise list all accounts. If the -mode flag is given in any of these cases,
however, list only those accounts that have the operational mode specified. If this
flag is repeated, or with the -long flag, more detail is displayed: device type,
account status, device serial number, counter value (for HOTP), clock drift value (for
TOTP), whether or not the account has a PIN (indicated by a "+" or "-" symbol), and
the time and date of the account's last modification.
-rename new-username
Rename the existing account for username to be new-username, and modify the new
account using command line arguments (as with -set[32]). 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.
-set
The -set flag is used to modify the existing account for username based on one or more
modifier arguments (-base, -counter, -digits, -disable or -enable, -key (or -key-file
or -key-prompt), -pin (or -pin-file or -pin-prompt), or -serial). The mode can also be
changed by specifying -mode, 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.
-sync password-list
In HOTP mode, this attempts to synchronize the server with the token for username. The
password-list is a comma-separated list of three successive passwords produced by the
user's token (this "auto-synchronize" function is also available through
local_token_authenticate[3]). The given sequence must match the computed sequence
exactly, 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's currently stored counter value, unless
one is provided using -counter. If unsuccessful, this operation could take a long time
before it terminates; the user must contact an administrator for assistance.
In TOTP mode, attempt to determine how closely synchronized the system clock is with
the token's clock and display the result. This information can be used to update the
user's token record to compensate for poorly synchronized clocks, or to adjust
validation parameters. The token's key and the name of the digest algorithm are
obtained for the token record belonging to username, 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 password-list is used. The
-totp-timestep, -digits, and -totp-base options are effective during this operation.
-test
Perform some self-tests, then exit. A non-zero exit status means an error occurred.
-totp-show num
Display a sequence of TOTP passwords using the parameters currently in effect:
interval size (-totp-timestep), number of digits (-digits), and base (-base). The
account's stored parameters are not modified. This is mainly intended for debugging
purposes.
If a username 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 num intervals before and after the current time,
together with the password for the current time are printed.
If no username is given, the program prompts for the key (which is echoed) 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.
-validate otp-value
If otp-value is the next expected one-time password, return an exit status of zero to
indicate success; any other value indicates failure. If username is given, parameters
for validation, including the key, are obtained from that account unless overridden on
the command line. The server's state is not changed; e.g., a HOTP counter is not
advanced. If no username is given, the -mode 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. dacstoken will test whether otp-value validates against the parameters in
effect.
The following modifier flags are understood:
-all
With -set and no username, apply the changes to all accounts. This can be used to
enable or disable all accounts, for example. The -inkeys and -outkeys flags are
honoured. If an error occurs processing stops immediately, in which case only some
accounts may have been modified.
-base num
Use num as the base (radix) when displaying an OTP. The value of num is restricted to
10 (the default), 16, or 32.
-counter num
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.
-digits num
Use num digits when displaying an OTP. The value of num is restricted to 6, 7, 8 (the
default), or 9 with base 10. It is restricted to 6 with base 32 and is ignored with
base 16 (hex output).
-disable
Disable the account for username. The local_token_authenticate module, and -auth and
-validate 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 -enable
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.
-enable
Enable the account for username. The local_token_authenticate module will allow the
user to authenticate. It is not an error to enable an already enabled account.
-hotp-window num
If the expected HOTP password does not match the given password, try to match up to
num passwords after the expected password in the sequence. A value of zero for num
disables this search.
-inkeys item_type
For decrypting secret keys, use the store identified by item_type, presumably
configured in dacs.conf.
-key keyval
Use keyval as the secret key, expressed as a hex digit string.
Security
Supplying a key on the command line is not secure because it may be visible to
other processes.
-key-file filename
Read the secret key, expressed as a hex digit string, from filename. If filename is
"-", the key is read from stdin.
-key-prompt
Prompt for the secret key, expressed as a hex digit string. The input is not echoed.
-mode otp-mode
This specifies (case insensitively) the type of token (the OTP device mode) for use
with -set, -create, and validation and synchronization operations. The otp-mode may be
either counter or hotp for counter mode, or time or totp for time-based mode. This
flag is required when creating a new account.
-outkeys item_type
For encrypting secret keys, use the store identified by item_type, presumably defined
in dacs.conf.
-pin pinval
Use pinval as the secret PIN for the account.
Security
Supplying a PIN on the command line is not secure because it may be visible to
other processes.
-pin-constraints str
Instead of using PASSWORD_CONSTRAINTS[14], use str (having the same syntax and
semantics) to describe the requirements for a PIN.
Note
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).
-pin-file filename
Read the secret PIN from filename. If filename is "-", the PIN is read from stdin.
-pin-prompt
Prompt for the secret PIN. The input is not echoed.
-rnd
Reserved for future use.
-seed str
Reserved for future use.
-serial str
The serial number, str, is a (purportedly) unique identifier assigned to the token.
This option is used with the -set, -create, and -list 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's serial number, or choose any suitably descriptive
string not already assigned to a device.
Note
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's serial number to form the dacstoken serial number. For software
tokens, the administrator might create a dacstoken serial number by appending
"-sw" to the vendor's serial number for the device.
-totp-delta num
Adjust the base time by num intervals (each of the step size number of seconds) when
computing a TOTP. The num may be negative, zero, or positive. This is used to correct
for inadequately synchronized clocks.
-totp-drift nwindows
For TOTP, use a window size of nwindows (in terms of the interval size) for
validation. If nwindows is 0, the computed TOTP value must match the given one
exactly. If nwindows is 1, for example, dacstoken will try to match the given TOTP
value in the previous, current, and next intervals. This allows the clocks in the
system running dacstoken (or local_token_authenticate) and token producing device to
be less well synchronized.
Security
Although it compensates for poorly synchronized clocks, increasing the value of
nwindows weakens the system by extending the lifetime of a one-time password.
-totp-hash alg
Use alg as the digest algorithm with TOTP. The value of alg is restricted to (case
insensitively) SHA1 (the default), SHA256, or SHA512.
-totp-timestep secs
Use secs as the interval size when computing a TOTP. It must be greater than zero. The
default is 30 seconds.
Security
Although it compensates for poorly synchronized clocks, increasing the value of
secs weakens the system by extending the lifetime of a one-time password.
-vfs vfs_uri
Use vfs_uri to override the VFS[33] 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.
Apart from error messages, which are printed to the standard error, all output goes to the
standard output.
Ordinarily, a dacsoption will be specified to select the jurisdiction on behalf of which
accounts are being managed.
EXAMPLES
These examples assume that the jurisdiction name to use is EXAMPLE and its federation
domain is example.com.
To use this authentication method, a DACS administrator might perform the following steps
for each OTP device assigned to a user:
1. Obtain a supported token, review how it is used for authentication, and select values
for the various parameters. Obtain the secret key for the device from the vendor; for
a programmable device, select a suitable random key and program it into the device.
The current counter values might also be obtained from the vendor, although it is
likely to initialized to zero; for a programmable device, set the counter value to
zero. Decide whether a PIN will be required (see TOKEN_REQUIRES_PIN[9]). If a software
client is being used, install the software on the user's device (or have the user do
so), and configure the software.
2. Decide where the account information will be stored and, if necessary, add a suitable
VFS[33] directive to dacs.conf. The default (found in site.conf) maintains the account
information in a file named auth_tokens within each jurisdiction's default private
area:
VFS "[auth_token]dacs-kwv-fs:${Conf::FEDERATIONS_ROOT}/\
${Conf::FEDERATION_DOMAIN}/${Conf::JURISDICTION_NAME}/auth_tokens"
3. Generate keys to encrypt the account information (see Tokens and secret keys[34]) and
decide where they will be stored; for example (your user ID, group ID, path,
jurisdiction name, and federation domain may vary):
% 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
If necessary, add a suitable VFS[33] directive to dacs.conf; the default, which is
used above, maintains the account information in a file named auth_token_keys within
each jurisdiction's default private area:
VFS "[auth_token_keys]dacs-fs:${Conf::FEDERATIONS_ROOT}/\
${Conf::FEDERATION_DOMAIN}/${Conf::JURISDICTION_NAME}/auth_token_keys"
4. If you need users to sign on through dacs_authenticate(8)[2], you must configure a
suitable Auth clause in dacs.conf, for example:
<Auth id="token">
URL "token"
STYLE "pass"
CONTROL "sufficient"
</Auth>
5. 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.
1. prepare a file containing an XML record[35] for each account to be created; if
PINs are to be used, assign a random PIN to each account;
2. use the -import[36] flag to create the accounts;
3. give the token device, username, and (if necessary) initial PIN to the user
(perhaps verifying identity), providing any necessary demonstration and
instructions;
4. 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.
To create a disabled account for user bobo for a HOTP device:
% dacstoken -uj EXAMPLE -mode hotp -serial 37000752 -key-file bobo.key -create bobo
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 -enable to create an enabled account.
Once an account has been created, it can be synchronized with the token. To synchronize
the HOTP token for user bobo:
% dacstoken -uj EXAMPLE -sync 433268,894121,615120 bobo
In this example, the particular token produced the three consecutive passwords 433268,
894121, and 615120. Note that the password sequence string that follows the -sync flag is
a single argument that cannot have any embedded spaces. If the key for this token is
19c0a3519a89b4a8034c5b9306db, the next password generated by this token should be 544323
(with counter value 13). This can be verified using -hotp-show:
% dacstoken -hotp-show 5 -counter 10 -key 19c0a3519a89b4a8034c5b9306db
000000000000000a: 433268
000000000000000b: 894121
000000000000000c: 615120
000000000000000d: 544323
000000000000000e: 002442
To enable the account for user bobo:
% dacstoken -uj EXAMPLE -enable -set bobo
To both set the PIN and enable the account for user bobo:
% dacstoken -uj EXAMPLE -enable -pin "CzAy" -set bobo
To list all accounts in detail:
% dacstoken -uj EXAMPLE -long
The -list flag is redundant because it is the default operation. The -mode, -counter, etc.
modifiers have no effect when listing.
To list only the account for bobo:
% dacstoken -uj EXAMPLE -list bobo
The exit status will be non-zero if this user does not have an account.
To display the account for the device with serial number 37000752:
% dacstoken -uj EXAMPLE -serial 37000752
The serial number, which should uniquely identify a token, is often printed on the token
or can be displayed by the token.
To set the counter value for the existing account of bobo:
% dacstoken -uj EXAMPLE -counter 9 -set bobo
This operation might be used for testing or with a software token. The -sync operation is
more appropriate for a hardware token.
To change the PIN for username bobo:
% dacstoken -uj EXAMPLE -pin-prompt -set bobo
The program will prompt for the new PIN.
To use an alternate account file, /secure/auth_tokens:
% dacstoken -uj EXAMPLE -vfs "dacs-kwv-fs:/secure/auth_tokens" -list
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:
VFS "[auth_token_keys_prev]dacs-fs:${Conf::FEDERATIONS_ROOT}/\
${Conf::FEDERATION_DOMAIN}/${Conf::JURISDICTION_NAME}/auth_token_keys.prev"
% 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
DIAGNOSTICS
The program exits 0, or 1 if an error occurred.
BUGS
HOTP should probably be called COTP, but HOTP came before TOTP. WOTP?
Listings may only be sorted by username.
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 (RFC
1305[37]) or equivalent be used on any host that runs DACS commands or web services.
The implementation of time-based tokens is based on the latest available Internet-Draft,
which is considered by the IETF to be a "work in progress". Hence the algorithm, its
implementation (including DACS accounts based on this operational mode), and documentation
are all subject to change.
TOTP password matching windows are symmetrical.
This functionality should probably be available through dacs_admin(8)[38] and
dacsauth(1)[39], but it's not.
Mutual authentication using tokens should be implemented.
Although release 1.4.25 introduced many improvements, some cause incompatibilities with
earlier versions of dacstoken.
SEE ALSO
RFC 4226[4], draft-mraihi-totp-timebased-05.txt[5], dacs_authenticate(8)[2],
dacs_token(8)[8], dacsgrid(1)[40], dacspasswd(1)[10], opie(4)[41], Mobile One Time
Passwords[42], mod_authn_otp[43]
AUTHOR
Distributed Systems Software (www.dss.ca[44])
ACKNOWLEDGEMENTS
Our sincere thanks to Authenex, Inc.[24] and HyperSecu Information Systems, Inc.[26] for
generously providing samples of their products and technical support.
COPYING
Copyright2003-2013 Distributed Systems Software. See the LICENSE[45] file that accompanies
the distribution for licensing information.
NOTES
1. dacsoptions
http://dacs.dss.ca/man/dacs.1.html#dacsoptions
2. dacs_authenticate
http://dacs.dss.ca/man/dacs_authenticate.8.html
3. local_token_authenticate
http://dacs.dss.ca/man/dacs_authenticate.8.html#token
4. RFC 4226
http://www.rfc-editor.org/rfc/rfc4226.txt
5. latest IETF Internet-Draft
http://www.ietf.org/id/draft-mraihi-totp-timebased-05.txt
6. Additional operational modes
http://www.ietf.org/id/draft-mraihi-mutual-oath-hotp-variants-11.txt
7. -convert flag
http://dacs.dss.ca/man/#convert_flag
8. dacs_token(8)
http://dacs.dss.ca/man/dacs_token.8.html
9. TOKEN_REQUIRES_PIN
http://dacs.dss.ca/man/dacs.conf.5.html#TOKEN_REQUIRES_PIN
10. dacspasswd(1)
http://dacs.dss.ca/man/dacspasswd.1.html
11. dacs_passwd(8)
http://dacs.dss.ca/man/dacs_passwd.8.html
12. PASSWORD_DIGEST
http://dacs.dss.ca/man/dacs.conf.5.html#PASSWORD_DIGEST
13. PASSWORD_SALT_PREFIX
http://dacs.dss.ca/man/dacs.conf.5.html#PASSWORD_SALT_PREFIX
14. PASSWORD_CONSTRAINTS
http://dacs.dss.ca/man/dacs.conf.5.html#PASSWORD_CONSTRAINTS
15. RFC 2104
http://www.rfc-editor.org/rfc/rfc2104.txt
16. FIPS 198
http://csrc.nist.gov/publications/fips/fips198/fips-198a.pdf
17. time(3)
http://www.freebsd.org/cgi/man.cgi?query=time&apropos=0&sektion=3&manpath=FreeBSD+9.1-RELEASE&format=html
18. dacsexpr(1)
http://dacs.dss.ca/man/dacsexpr.1.html
19. man-in-the-middle attack
http://en.wikipedia.org/wiki/Man-in-the-middle_attack
20. revocation list
http://dacs.dss.ca/man/dacs.acls.5.html#revocation_list
21. local_passwd_authenticate
http://dacs.dss.ca/man/dacs_authenticate.8.html#passwd
22. DACS identities
http://dacs.dss.ca/man/dacs.1.html#gloss_identity
23. dacskey(1)
http://dacs.dss.ca/man/dacskey.1.html
24. Authenex A-Key 3600
http://www.authenex.com
25. Feitian Technologies
http://www.ftSafe.com
26. HyperSecu Information Systems
http://www.hypersecu.com
27. OATH Token
http://oathtoken.googlecode.com
28. iPod Touch, iPhone, and iPad
http://itunes.apple.com/us/app/oath-token/id364017137?mt=8
29. iOATH Lite
http://itunes.apple.com/ca/app/ioath-lite/id327109243?mt=8
30. Photo
http://dacs.dss.ca/otp-tokens2.jpg
31. -validate
http://dacs.dss.ca/man/#validate_flag
32. -set
http://dacs.dss.ca/man/#set_flag
33. VFS
http://dacs.dss.ca/man/dacs.conf.5.html#VFS
34. Tokens and secret keys
http://dacs.dss.ca/man/#security1
35. XML record
http://dacs.dss.ca/man/#user_provisioning
36. -import
http://dacs.dss.ca/man/import_flag
37. RFC 1305
http://www.rfc-editor.org/rfc/rfc1305.txt
38. dacs_admin(8)
http://dacs.dss.ca/man/dacs_admin.8.html
39. dacsauth(1)
http://dacs.dss.ca/man/dacsauth.1.html
40. dacsgrid(1)
http://dacs.dss.ca/man/dacsgrid.1.html
41. opie(4)
http://www.freebsd.org/cgi/man.cgi?query=opie&apropos=0&sektion=4&manpath=FreeBSD+9.1-RELEASE&format=html
42. Mobile One Time Passwords
http://motp.sourceforge.net
43. mod_authn_otp
http://code.google.com/p/mod-authn-otp
44. www.dss.ca
http://www.dss.ca
45. LICENSE
http://dacs.dss.ca/man/../misc/LICENSE
