Provided by: dacs_1.4.40-2_amd64 bug


       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

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

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

           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.

           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)

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

       ·   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

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

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

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

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

           Recognized 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

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

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


       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

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

           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

           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

           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


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

                                       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

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

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

                                           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

                                       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.

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

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

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

                                   -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

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

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

            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

           % 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/
           % 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 helpful.


       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], mod_authn_otp[59]


       Distributed Systems Software ([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


       61. HyperSecu Information Systems, Inc.

       62. LICENSE