Provided by: dacs_1.4.38a-2build1_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] [-ignore-key-length]
[-inkeys item_type] [-issuer name] [[-key keyval] | [-key-enc enc] | [-key-file filename] |
[-key-prompt]
] [-mode otp-mode] [-nl] [-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-time secs] [-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. 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 RFC 4226[4], and the time-based one-time
password mode (TOTP), as specified by RFC 6238[5]. Additional operational modes called OCRA (OATH
Challenge-Response Algorithms), described in RFC 6287[6], 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. By default, a PIN is required. The directive 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. The PIN is not stored. 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 (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.
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 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 (OTPs)
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 (see RFC 4226[4]) 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 -ignore-key-length flag, and the algorithm used to encode the
key can be specified using the -key-enc 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 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 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 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 can be used to configure or reconfigure the item types.
Multiple instances of each item type can exist, provided the appropriate one for dacstoken to use can be
determined at run time and specified through a VFS[23] directive or -vfs flag.
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 always encrypted and converted to a base-64 representation when it is stored in the
account file by dacstoken. 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)[24]). 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[25] one-time password (HOTP) hardware token;
• Feitian Technologies[26] OTP C100 and OTP C200 one-time password hardware tokens, provided by
HyperSecu Information Systems[27]; and
• Google Authenticator[28].
• The open source[29] FreeOTP Authenticator[30] by Red Hat[31], which is available for a
variety of platforms.
• OATH Token[32] software application by Archie Cobbs, which implements both HOTP and TOTP on
the iPod Touch, iPhone, and iPad[33].
• The OTP Auth[34] software application for the iPod Touch, iPhone, and iPad by Roland Moers.
There are many other free software implementations. Other manufacturers interested in having
their products supported by DACS are welcome to contact[35] Dss.
• Photo[36]: 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 provisioning, backup, and portability. The account information can be written in
a simple, application-specific (almost) XML format, or Google's KeyUriFormat[37], which is understood by
several OTP applications.
The -format flag (see dacsoptions[38]) can be used to select the xml format (the default) or the uri
format for export.
Note
At present, the uri format cannot be imported by dacstoken.
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
An official 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.
XML Provisioning Format
The XML 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 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 ("'" 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:
SHA-1 (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>
KeyUriFormat Provisioning Format
The KeyUriFormat[37] provisioning format is supported by several OTP clients, such as FreeOTP[30] and
Google Authenticator[28]. In this format, a URI describes the current state of an account. The URI
can be encoded into a QR Code[39] image (a two-dimensional barcode), which these and other OTP
clients can recognize and conveniently and correctly import using a device's camera. Also, software
such as zbarimg, a component of the ZBar[40] suite, can scan and decode barcodes that it finds in
image files.
An account can be created by dacstoken, 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's client software. A QR Code generator that has been successfully used for this purpose with
the iPhone is qrencode, which is distributed with the libqrencode library[41].
Notes
• 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.
• The secret query parameter (the OTP seed) is base-32 encoded[42] without padding.
• A newline should not be encoded in the barcode.
• The -issuer flag can be used to specify the name of the token issuer.
• A QR barcode can be easily copied by an attacker for reuse.
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[43], 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[44]. 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.
-issuer name
Use the string name as the token issuer when exporting an account in KeyUriFormat format.
-l
-list
-L
-long
If username is provided, list the corresponding account (it is an error if the account does not
exist). Otherwise, if the -serial 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 -mode flag, or if
-mode is absent, all accounts. If -l (equivalently, -list) is repeated, or with the -long flag
(equivalently, -L), more detail is displayed for each account:
• account name,.RE
• device type (mode of operation),.RE
• account status,.RE
• device serial number,.RE
• counter value (for HOTP),.RE
• clock drift value (for TOTP),.RE
• whether or not the account has a PIN (indicated by a "+" or "-" symbol),
and
• the time and date of the account's last modification..RE
Examples:
% 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
-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[44]). 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) 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 num is zero, however, the program does not wait for user
input and prints only one password.
-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.
-ignore-key-length
Do not enforce the minimum key length requirement (in bytes, applied to
the decoded keyval string argument specified by -key).
-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 by default
(see -key-enc).
Security
Supplying a key on the command line is not secure because it may be
visible to other processes.
-key-enc enc
The secret key, however it is read by dacstoken, has been encoded using
algorithm enc. Recognized values (case insensitive) for enc are "hex",
"base32" (RFC 4648[45]), and "none" (plaintext). The default is "hex".
-key-file filename
Read the secret key from filename, expressed as a hex digit string by
default (see -key-enc). If filename is "-", the key is read from stdin.
-key-prompt
Prompt for the secret key, expressed as a hex digit string by default
(see -key-enc). 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, listing accounts, 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, case
insensitively. This flag is required when creating a new account.
-nl
When exporting the uri format, suppress the newline. When generating a QR
barcode from the URI, a newline should not be encoded.
-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 SHA1 (the default), SHA256, or SHA512. Digest name matching is
described in dacs.exprs(5)[46].
-totp-time secs
Use secs, expressed as the number of seconds since the Unix Epoch,
instead of the current date and time.
-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[23] 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 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 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 for DACS and, if necessary, add a suitable
VFS[23] 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[47]) 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[23] 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. Here is one way:
1. prepare a file containing an XML record[48] for each account to be created; if PINs are to be
used, assign a random PIN to each account;
2. use the -import[49] 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.
Another method of provisioning a token-based account using a QR barcode might follow steps similar to
these for user alice:
1.
% dacstoken -format uri -export -issuer DSS -nl alice > alice.uri
% qrencode -o alice.png < alice.uri
% chmod 0600 alice.uri alice.png
The exported URI put in alice.uri might look something like this:
otpauth://totp/DSS:alice?secret=NBSWY3DPFR3W64TMMQXGCYTDMRSQ&issuer=DSS&algorithm=SHA1&digits=8&period=30
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.
3. 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 DACS 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.
% dacstoken -hotp-show 3 alice
0000000000000000: 070440
0000000000000001: 089277
0000000000000002: 253240
Alternatively, a web page might be provided to help users verify correct operation and enable
their account.
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
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 -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 the value 19c0a3519a89b4a8034c5b9306db,
supplied as a hex string, 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 -ignore-key-length
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 -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
The following examples outline how dacstoken might be used to generate the same output sequence as Google
Authenticator[50] (tested with Version 2.1.0.2212). Here, the key is "mfrggzdf", which is the base-32
encoding[42] of the string "abcde". Since this an unsafe, five-byte long key, it must be expressly
allowed by using the -ignore-key_length 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, dacstoken displays ten consecutive codes, starting with the code for a counter
value of one:
% dacsexpr -e 'encode(base32,"abcde")'
"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
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):
% dacstoken -un -totp-show 0 -digits 6 -key mfrggzdf -key-enc base32 -ignore-key-length
TOTP=525711 [at t=1371760542]
To generate some of the RFC 6238[5], Appendix B test vector values:
% 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 \
-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]
The dacsexpr(1)[18] base-32 encoding and decoding functions[51] may be helpful.
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[52]) or equivalent be used on any host that runs DACS commands or web services.
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 RFC 6238[5], TOTP: Time-Based One-Time
Password Algorithm, and interoperate with other conformant hardware and software tokens. DACS passes
both documents' test vectors.
TOTP password matching windows are symmetrical.
This functionality should probably be available through dacs_admin(8)[53] and dacsauth(1)[54], 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[55], RFC 6238[5], dacs_authenticate(8)[2],
dacs_token(8)[8], dacsgrid(1)[56], dacspasswd(1)[10], opie(4)[57], Mobile One Time Passwords[58],
mod_authn_otp[59]
AUTHOR
Distributed Systems Software (www.dss.ca[60])
ACKNOWLEDGEMENTS
Our sincere thanks to Authenex, Inc.[25] and HyperSecu Information Systems, Inc.[27] for generously
providing samples of their products and technical support.
COPYING
Copyright2003-2016 Distributed Systems Software. See the LICENSE[61] 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. RFC 6238
http://www.rfc-editor.org/rfc/rfc6238.txt
6. RFC 6287
http://www.rfc-editor.org/rfc/rfc6287.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+10.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. VFS
http://dacs.dss.ca/man/dacs.conf.5.html#VFS
24. dacskey(1)
http://dacs.dss.ca/man/dacskey.1.html
25. Authenex A-Key 3600
http://www.authenex.com
26. Feitian Technologies
http://www.ftSafe.com
27. HyperSecu Information Systems
http://www.hypersecu.com
28. Google Authenticator
https://itunes.apple.com/ca/app/google-authenticator/id388497605
29. open source
https://fedorahosted.org/freeotp
30. FreeOTP Authenticator
https://itunes.apple.com/ca/app/freeotp-authenticator/id872559395
31. Red Hat
http://www.redhat.com
32. OATH Token
http://oathtoken.googlecode.com
33. iPod Touch, iPhone, and iPad
http://itunes.apple.com/us/app/oath-token/id364017137
34. OTP Auth
https://itunes.apple.com/ca/app/otp-auth/id659877384
35. contact
http://www.dss.ca/contactus.html
36. Photo
http://dacs.dss.ca/otp-tokens2.jpg
37. KeyUriFormat
https://code.google.com/p/google-authenticator/wiki/KeyUriFormat
38. dacsoptions
http://dacs.dss.ca/man/dacs.1.html#format-arg
39. QR Code
http://en.wikipedia.org/wiki/QR_code
40. ZBar
http://zbar.sourceforge.net
41. libqrencode library
http://fukuchi.org/works/qrencode/
42. base-32 encoded
https://en.wikipedia.org/wiki/Base32
43. -validate
http://dacs.dss.ca/man/#validate_flag
44. -set
http://dacs.dss.ca/man/#set_flag
45. RFC 4648
http://www.rfc-editor.org/rfc/rfc4648.txt
46. dacs.exprs(5)
http://dacs.dss.ca/man/dacs.exprs.5.html#digest
47. Tokens and secret keys
http://dacs.dss.ca/man/#security1
48. XML record
http://dacs.dss.ca/man/#user_provisioning
49. -import
http://dacs.dss.ca/man/#import_flag
50. Google Authenticator
http://en.wikipedia.org/wiki/Google_Authenticator
51. base-32 encoding and decoding functions
http://dacs.dss.ca/man/dacs.exprs.5.html#encode
52. RFC 1305
http://www.rfc-editor.org/rfc/rfc1305.txt
53. dacs_admin(8)
http://dacs.dss.ca/man/dacs_admin.8.html
54. dacsauth(1)
http://dacs.dss.ca/man/dacsauth.1.html
55. draft-mraihi-totp-timebased-05.txt
http://www.ietf.org/id/draft-mraihi-totp-timebased-05.txt
56. dacsgrid(1)
http://dacs.dss.ca/man/dacsgrid.1.html
57. opie(4)
http://www.freebsd.org/cgi/man.cgi?query=opie&apropos=0&sektion=4&manpath=FreeBSD+10.1-RELEASE&format=html
58. Mobile One Time Passwords
http://motp.sourceforge.net
59. mod_authn_otp
http://code.google.com/p/mod-authn-otp
60. www.dss.ca
http://www.dss.ca
61. LICENSE
http://dacs.dss.ca/man/../misc/LICENSE
DACS 1.4.38a 02/05/2018 DACSTOKEN(1)
