DACSTOKEN(1)                  DACS Commands Manual                  DACSTOKEN(1)

       dacstoken - administer hash-based one-time passwords

       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]

       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.

           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

           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

           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

           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

       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.

           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 -e "random(string, 20)"

           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.

           The radix in which passwords are displayed.

           For HOTP mode only, the current counter value.

           The number of digits in each one-time password.

           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:

           When validating a HOTP password, the maximum number of passwords to
           consider after the expected password.

           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.

           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.

           For HOTP mode only, the number of consecutive one-time passwords
           required to synchronize the account with the device.

           The name of the DACS account bound to the device.

       Authentication based on one-time password devices has the following

       •   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

       •   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

       •   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.

       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

       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

       The -vfs can be used to configure or reconfigure the item types.

       Multiple instances of each item type can exist, provided the correct 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.

           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.

           •   This authentication method has been tested against the following
               OTP products:

               •   Authenex A-Key® 3600[25] one-time password (HOTP) hardware

               •   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

               •   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.

           At present, the uri format cannot be imported by dacstoken.

           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.

           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

       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
           "&quot;", respectively), as must the "<" (less than) and "&"
           (ampersand) characters. A ">" (greater than) character may optionally
           be replaced by a "&gt;" sequence, but no other entity references are

           Recognized attributes are:

           •   b:
                 -- radix for OTP value
                 10 (default),
                 16, or 32]

           •   c:
                 -- current counter value for HOTP, in hex if preceded
                 by "0x" (or "0X"), decimal otherwise
                 default is 0]

           •   d:
                 OTP device mode
                 -- "c" (for HOTP)
                 or "t" (for TOTP)

           •   dn:
                 -- one of the Secure Hash Algorithms
                 SHA-1 (default),
                 SHA224, SHA256,
                 SHA384, SHA512]

           •   dr:
                 -- clock adjustment, in seconds, for TOTP

           •   ek:
                 -- encrypted secret key, base-64 encoded
                 OTP account records only]

           •   en:
                 -- 1 for enabled,
                 0 for disabled

           •   k:
                 -- unencrypted secret key

           •   lu:
                 -- Unix time of last record update
                 [Optional: default is current time]

           •   nd:
                 -- number of digits for OTP value
                 default is 6 for HOTP,
                 8 for TOTP]

           •   p:
                 -- plaintext PIN value for the account
                 unless ph is present,
                 for import only]

           •   ph:
                 -- hashed PIN value for the account
                 generated by dacstoken
                 for export and OTP account files only]

           •   s:
                 -- unique identifier string for the device

           •   ts:
                 -- time-step value, in seconds, for TOTP
                 default is 30]

           •   u:
                 -- a valid DACS username associated with this account

           The following example describes two accounts that might be created
           using the -import flag:

               <!-- Staff OTP tokens for DACS authentication -->
               <otp_token u="ietf" d="t" en="1" s="totp-ietf &quot;draft&quot;" k="3132333435363738393031323334353637383930" dn="SHA1" ts="30"/>
               <otp_token u="ipod-c" d="c" en="1" s="ipodc-9C841SD4203" k="19c0a3519a89b4a8034c5b9306db" dn="SHA1" c="0" nd="6" b="10"/>

       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].

               •   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

               •   A QR barcode can be easily copied by an attacker for reuse.

       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

           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).

           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

           Delete the account for username. The device's secret key and other
           operational parameters will be lost.

           Delete the PIN, if present, on the account for username, leaving the
           account without a PIN.

           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 -

           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.

           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


                                           % dacstoken -uj EXAMPLE -long
                                           % dacstoken -uj EXAMPLE -mode hotp -L

                                   -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.

                                       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

                                       Perform some self-tests, then exit. A
                                       non-zero exit status means an error

                                   -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

                                       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

                                   -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:

                                       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

                                   -base num
                                       Use num as the base (radix) when
                                       displaying an OTP. The value of num is
                                       restricted to 10 (the default), 16, or

                                   -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 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 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

                                   -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.

                                       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

                                           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.

                                       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.

                                       When exporting the uri format, suppress
                                       the newline. When generating a QR barcode
                                       from the URI, a newline should not be

                                   -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

                                           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.

                                           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

                                       Prompt for the secret PIN. The input is
                                       not echoed.

                                       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.

                                           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

                                   -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

                                   -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.

                                           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

                                   -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.

                                           Although it compensates for poorly
                                           synchronized clocks, increasing the
                                           value of secs weakens the system by
                                           extending the lifetime of a one-time

                                   -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.

       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}/\

        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

               VFS "[auth_token_keys]dacs-fs:${Conf::FEDERATIONS_ROOT}/\

        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"

        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

            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

            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:


                   % 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:


            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 better suited to 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}/\

           % 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 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")'
           % 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

       The program exits 0, or 1 if an error occurred.

       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.

       The shared secret keys used to generate one-time passwords are protected
       on the server side by storing them in encrypted form. But since the
       decryption key must be readily accessible to DACS at run-time for token
       generation, a server compromise could make it straightforward for an
       attacker to obtain both an account file and the symmetric key used to
       encrypt/decrypt secret keys unless appropriate steps are not taken. One
       idea is to involve the user-provided PIN or password in the construction
       or encryption of the symmetric key. Also, all shared secret keys must be
       kept private on the client side.

       RFC 4226[4], draft-mraihi-totp-timebased-08.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],

       Distributed Systems Software (www.dss.ca[60])

       Our sincere thanks to Authenex, Inc.[25] and HyperSecu Information
       Systems, Inc.[61] for generously providing samples of their products and
       technical support.

       Copyright © 2003-2018 Distributed Systems Software. See the LICENSE[62]
       file that accompanies the distribution for licensing information.

        1. dacsoptions

        2. dacs_authenticate

        3. local_token_authenticate

        4. RFC 4226

        5. RFC 6238

        6. RFC 6287

        7. -convert flag

        8. dacs_token(8)


       10. dacspasswd(1)

       11. dacs_passwd(8)




       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. VFS

       24. dacskey(1)

       25. Authenex A-Key® 3600

       26. Feitian Technologies

       27. HyperSecu Information Systems

       28. Google Authenticator

       29. open source

       30. FreeOTP Authenticator

       31. Red Hat

       32. OATH Token

       33. iPod Touch, iPhone, and iPad

       34. OTP Auth

       35. contact

       36. Photo

       37. KeyUriFormat

       38. dacsoptions

       39. QR Code

       40. ZBar

       41. libqrencode library

       42. base-32 encoded

       43. -validate

       44. -set

       45. RFC 4648

       46. dacs.exprs(5)

       47. Tokens and secret keys

       48. XML record

       49. -import

       50. Google Authenticator

       51. base-32 encoding and decoding functions

       52. RFC 1305

       53. dacs_admin(8)

       54. dacsauth(1)

       55. draft-mraihi-totp-timebased-08.txt

       56. dacsgrid(1)

       57. opie(4)

       58. Mobile One Time Passwords

       59. mod_authn_otp

       60. www.dss.ca

       61. HyperSecu Information Systems, Inc.

       62. LICENSE

DACS 1.4.40                        02/19/2019                       DACSTOKEN(1)