table of contents
DACSTOKEN(1) | DACS Commands Manual | DACSTOKEN(1) |
NAME¶
dacstoken - administer hash-based one-time passwordsSYNOPSIS¶
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.•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
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.% dacsexpr -e "random(string, 20)" "bb2504780e8075a49bd88891b228fc7216ac18d9"
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.•This authentication method has been
tested against the following OTP products:
Other manufacturers interested in having their products supported by DACS
are welcome to contact Dss.
•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.
•
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]
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]
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]
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]
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]
clock-drift
-- clock adjustment, in seconds, for TOTP
[Optional]
•ek:
encrypted-key
-- encrypted secret key, base-64 encoded
[Required:
OTP account records only]
encrypted-key
-- encrypted secret key, base-64 encoded
[Required:
OTP account records only]
•en:
enabled-status
-- 1 for enabled,
0 for disabled
[Required]
enabled-status
-- 1 for enabled,
0 for disabled
[Required]
•k:
plaintext-key
-- unencrypted secret key
[Required]
plaintext-key
-- unencrypted secret key
[Required]
•lu:
last-update
-- Unix time of last record update
[Optional: default is current time]
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]
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]
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]
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]
serial-number
-- unique identifier string for the device
[Required]
•ts:
time-step
-- time-step value, in seconds, for TOTP
[Optional:
default is 30]
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:
username
-- a valid DACS username associated with this account
[Required]
<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>
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-valueThis flag is like -validate[31],
except:
An exit status of zero indicates successful authentication, while any other
value means authentication failed.
-convert filename
•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.
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:
Later, you might do something like:
-h
% dacstoken -uj EXAMPLE -export | openssl enc -aes-256-cbc > dacstoken-exported.enc
% openssl enc -d -aes-256-cbc < dacstoken-exported.enc | dacstoken -uj EXAMPLE -import -
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
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
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):
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:
% 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
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.
To create a disabled account for user bobo for a HOTP device:
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.
% dacstoken -uj EXAMPLE -mode hotp -serial 37000752 -key-file bobo.key -create bobo
% dacstoken -uj EXAMPLE -sync 433268,894121,615120 bobo
% dacstoken -hotp-show 5 -counter 10 -key 19c0a3519a89b4a8034c5b9306db 000000000000000a: 433268 000000000000000b: 894121 000000000000000c: 615120 000000000000000d: 544323 000000000000000e: 002442
% dacstoken -uj EXAMPLE -enable -set bobo
% dacstoken -uj EXAMPLE -enable -pin "CzAy" -set bobo
% dacstoken -uj EXAMPLE -long
% dacstoken -uj EXAMPLE -list bobo
% dacstoken -uj EXAMPLE -serial 37000752
% dacstoken -uj EXAMPLE -counter 9 -set bobo
% dacstoken -uj EXAMPLE -pin-prompt -set bobo
% dacstoken -uj EXAMPLE -vfs "dacs-kwv-fs:/secure/auth_tokens" -list
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¶
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-2012 Distributed Systems Software. See the LICENSE[45] file that accompanies the distribution for licensing information.NOTES¶
- 1.
- dacsoptions
- 2.
- dacs_authenticate
- 3.
- local_token_authenticate
- 4.
- RFC 4226
- 5.
- latest IETF Internet-Draft
- 6.
- Additional operational modes
- 7.
- -convert flag
- 9.
- TOKEN_REQUIRES_PIN
- 10.
- dacspasswd(1)
- 11.
- dacs_passwd(8)
- 12.
- PASSWORD_DIGEST
- 13.
- PASSWORD_SALT_PREFIX
- 14.
- PASSWORD_CONSTRAINTS
- 15.
- RFC 2104
- 16.
- FIPS 198
- 17.
- time(3)
- 18.
- dacsexpr(1)
- 19.
- man-in-the-middle attack
- 20.
- revocation list
- 21.
- local_passwd_authenticate
- 22.
- DACS identities
- 23.
- dacskey(1)
- 24.
- Authenex A-Key 3600
- 25.
- Feitian Technologies
- 26.
- HyperSecu Information Systems
- 27.
- OATH Token
- 28.
- iPod Touch, iPhone, and iPad
- 29.
- iOATH Lite
- 30.
- Photo
- 31.
- -validate
- 32.
- -set
- 33.
- VFS
- 34.
- Tokens and secret keys
- 35.
- XML record
- 36.
- -import
- 37.
- RFC 1305
- 38.
- dacs_admin(8)
- 39.
- dacsauth(1)
- 40.
- dacsgrid(1)
- 41.
- opie(4)
- 42.
- Mobile One Time Passwords
- 43.
- mod_authn_otp
- 44.
- www.dss.ca
- 45.
- LICENSE
10/22/2012 | DACS 1.4.27b |