dacstoken

DACSTOKEN(1)                 DACS Commands Manual                 DACSTOKEN(1)



NAME
       dacstoken - administer hash-based one-time passwords

SYNOPSIS
       dacstoken [dacsoptions[1]] [-all] [-base num] [-counter num]
                 [-digits num]
                 [-disable | -enable] [-hotp-window num] [-inkeys item_type]
                 [[-key keyval] | [-key-file filename] | [-key-prompt]]
                 [-mode otp-mode] [-outkeys item_type]
                 [[-pin pinval] | [-pin-file filename] | [-pin-prompt]]
                 [-pin-constraints str]
                 [-rnd] [-seed str] [-serial str] [-totp-delta num]
                 [-totp-drift nwindows] [-totp-hash alg]
                 [-totp-timestep secs] [-vfs vfs_uri] [op-spec] [username]

DESCRIPTION
       This program is part of the DACS suite.

       The dacstoken utility administers DACS accounts associated with
       one-time password (OTP) generating devices (tokens) or software-based
       clients. Using command line options, it also computes OTP values; token
       account parameters can be overridden, but accounts are not even
       required.

       Strong, two-factor authentication can be provided when
       dacs_authenticate[2] is configured to use the
       local_token_authenticate[3] authentication module or when dacstoken is
       used as a standalone program to validate passwords. Both the HMAC-based
       one-time password mode (HOTP), based on an event counter and specified
       by RFC 4226[4], and the time-based one-time password mode (TOTP), as
       specified by the latest IETF Internet-Draft[5] proposal, are supported.
       Additional operational modes[6] called OCRA (OATH Challenge-Response
       Algorithms), described in an IETF Internet-Draft, are not yet fully
       supported.

           Note
           This version of dacstoken incorporates many changes that are not
           backward compatible with release 1.4.24a and earlier. Some command
           line flags function differently, and the format of the account file
           has changed. If you have used this command in earlier releases,
           please make a backup copy of your token account file and review
           this manual page carefully before proceeding (note the -convert
           flag[7] in particular).

           Important
           No vendor-supplied software is required by dacstoken to supply its
           functionality. The devices currently supported do not need any
           registration or configuration interaction with vendors and
           dacstokendoes not interact with vendors' servers or use any
           proprietary software. Vendor-supplied software may be required to
           perform initialization or configuration for other token devices,
           however, and dacstoken does not provide such support for them.

       Each token device generally corresponds to exactly one account that is
       managed by dacstoken, although some vendors produce tokens that can
       support multiple accounts.

       To summarize, this utility:

       ·   creates and administers DACS accounts associated with counter-based
           and time-based one-time passwords

       ·   provides validation and testing functionality

       ·   provides a command line authentication capability


           Security
           Only the DACS administrator should be able to successfully run this
           program from the command line. Because DACS keys and configuration
           files, including the file used to store accounts, must be
           restricted to the administrator, this will normally be the case,
           but a careful administrator will set file permissions to deny
           access to all other users.

           Note
           The dacs_token(8)[8] web service provides users with limited
           self-service functionality to set or reset their account PIN and
           synchronize their token. It also has a demonstration mode to
           simplify testing and evaluation.

   PINs (Account Passwords)
       A dacstoken account can optionally have a PIN (i.e., a password)
       associated with it. To authenticate against such an account, a user
       must provide the one-time password produced by the token and the PIN.
       The TOKEN_REQUIRES_PIN[9] configuration directive determines whether a
       PIN must be provided when creating or importing an account; it does not
       apply in conjunction with the -delpin flag, since only an administrator
       should be able to perform that function.

       A hash of the PIN is stored in the account record rather than the PIN
       itself. The same method used by dacspasswd(1)[10] and
       dacs_passwd(8)[11] is applied, and depends on the PASSWORD_DIGEST[12]
       and PASSWORD_SALT_PREFIX[13] directives in effect. If
       PASSWORD_DIGEST[12] is configured, that algorithm is used, otherwise a
       compile-time default (SHA1) is used. If a user forgets the PIN, the old
       one cannot be recovered so it must either be deleted or a new one must
       be set.

       Some token devices have a PIN capability built into them. The user must
       enter a PIN into the device before the device will emit a one-time
       password. This "device PIN" is completely distinct from the account PIN
       that is managed by dacstoken, and this manual is only concerned with
       the dacstokenPIN. The device PIN should always be used when possible;
       the dacstokenPIN is strongly recommended and is required for two-factor
       authentication (unless an additional authentication factor is applied
       in some other way).

       Since only the administrator is allowed to run this command, no
       restrictions are imposed on the length or quality of the PINs that the
       administrator supplies; a warning message will be emitted, however, if
       the password is considered to be weak as determined by the
       PASSWORD_CONSTRAINTS[14] directive.

   One-Time Passwords
       Both kinds of one-time password device compute a password value by
       employing a secure keyed hash algorithm (RFC 2104[15], FIPS 198[16]).
       In the counter-based method, the device and server share a secret key
       and a counter value which are hashed to yield a numerical value
       displayed in a certain radix with a certain number of digits.
       Successful authentication requires the device and server to compute
       matching passwords. Each time the device produces a password, it
       increments its counter. When the server receives a matching password,
       it increments its counter. Because it is possible for the two counters
       to become unsynchronized, the server's matching algorithm will
       typically allow a client's password to fall within a "window" of
       counter values. The time-based method is similar, the main difference
       being that the current Unix time (as returned by time(3)[17], for
       instance) is used to establish a "time-step window" that serves as a
       counter value in the computation of the secure hash. Because the
       real-time clocks on the device and server may not be sufficiently
       synchronized, the server's matching algorithm must also allow a
       client's password to fall within some number of time-step windows for
       these devices.

           Security
           A token may be assigned a permanent secret key (sometimes called an
           OTP seed) by its manufacturer or the key may be programmable. This
           secret key is used by the token's password generation procedure and
           it is critical that it be kept private. If the token is not
           programmable, the key is obtained from the vendor (for a HOTP
           token, typically by providing the device's serial number and any
           three consecutive passwords). A record of each mapping from serial
           number to secret key should be kept in a secure location.

           If the secret key is programmable, as it is likely to be with a
           software client, it is required to be at least 128 bits in length;
           a minimum of 160 bits is recommended. The key is represented by a
           16 (or more) character long hexadecimal string. The key should be
           obtained from a cryptographic-quality source of random bits. Some
           clients may be capable of generating a suitable key, but you may
           use dacsexpr(1)[18]:

               % dacsexpr -e "random(string, 20)"
               "bb2504780e8075a49bd88891b228fc7216ac18d9"

           Tip
           Tokens can be used for authentication purposes other than computer
           sign on. For example, by providing an account number, PIN, and
           token value, customers can quickly be authenticated over the phone,
           reducing or eliminating the need for expensive and time-consuming
           security questions.

       One-time password devices and applications have the following
       operational parameters. These parameters determine the password
       sequence that is generated. Some operational parameters may be fixed
       (by the relevant standard or due to the implementation), while others
       may be partially or completely configurable by the user. Please refer
       to the references and manufacturers' documentation for details.

       base
           The radix in which passwords are displayed.

       counter
           For HOTP mode only, the current counter value.

       digits
           The number of digits in each one-time password.

       key
           The secret key (OTP seed).

       serial number
           A unique identifier or name for the device.

       time step size
           For TOTP mode only, the width of each time interval, in seconds.
           The same password will be generated within a given interval; i.e.,
           this is the "lifetime" or validity period of each TOTP password.

       In addition to these parameters, dacstoken employs several per-account
       (i.e., per-device) parameters:

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

       drift
           For TOTP mode only, the number of seconds by which to adjust the
           server's clock forward or backward to better synchronize it with
           the device. This is used to compensate for tokens or client
           software whose clocks are not well synchronized with the server's.

       drift-window
           For TOTP mode only, but analogous to the accept-window, the maximum
           number of intervals (each of the time step size) to search forward
           and backward when validating against a given password.

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

       username
           The name of the DACS account bound to the device.

       Authentication based on one-time password devices has the following
       advantages:

       ·   Each time a user authenticates, a different password will be
           generated (with high probability); users cannot therefore jot down
           "the password" because the password is always changing; users
           cannot forget their password;

       ·   Once used, a HOTP mode password is immediately "consumed" and is
           unlikely to be used again for a long time; with suitable
           configuration parameters, a TOTP mode password automatically
           "expires" within a relatively short time interval and is unlikely
           to be used again for a long time;

       ·   If no correction for clock drift is required, a TOTP mode account
           can have read-only operation;

       ·   Because the password is unlikely to be an easily-guessed number or
           string, it should be stronger than most user-selected passwords;

       ·   A HOTP token can be the basis of a mutual ("bidirectional")
           authentication method; the server shows the user his token's next
           password to confirm its identity (with both parties advancing their
           counters), then the client shows the server the next password to
           confirm his identity;

       ·   Should a key sniffer be installed on the user's computer, a sniffed
           password does not do an attacker any good unless a
           man-in-the-middle attack[19] is possible; given N consecutive
           passwords it is still very difficult to compute password N + 1
           without knowing the secret key;

       ·   It is more difficult for users to share an account (although users
           might sometimes view this as an inconvenience);

       ·   If a dacstokenPIN is assigned to an account and an attacker obtains
           the account's token, it is still difficult for the attacker to
           authenticate without knowing the PIN;

       ·   A quick and immediately effective way to disable an account is by
           simply seizing a hardware token (e.g., if an employee is fired),
           although an account can be disabled by this program or using the
           revocation list[20];

       ·   In the case of a software client that runs on a mobile device, such
           as a phone or PDA, users are already carrying the device with them;
           free clients are available, so there may be no additional cost
           (note that mobile devices may not offer the same tamper-resistance,
           durability, key secrecy, clock accuracy, etc. of a hardware token).

       One-time password devices have the following potential disadvantages:

       ·   There is a one-time expense for a hardware token (depending on the
           purchase volume, you can expect to pay $10-$100 USD each), and
           there is the possibility of having to replace a lost or broken
           token, or a token's battery (some units have a non-replaceable
           battery, making them disposable after a few years);

       ·   Initial configuration is somewhat more difficult than with other
           authentication methods, and users unfamiliar with the devices will
           have to be instructed on their use;

       ·   Although they are typically quite small (e.g., 5cm x 2cm x 1cm) and
           can be attached to a keychain or lanyard, or kept in a wallet,
           users may wince at having to carry a token around with them;

       ·   Users can forget to have their token with them or lose the token;

       ·   A mobile device (with a software client) is probably a likely
           target for theft, more so than a hardware token (hence the extra
           importance of a PIN for this device);

       ·   Unlike a hardware token where the key is burned into inaccessible,
           tamper-proof memory, the key configured into a software client is
           likely to be readable by its owner, making sharing of the account
           possible;

       ·   Entering a 40 character or longer seed value into a mobile device
           can be frustrating and prone to error;

       ·   Once a TOTP device generates a password, a new password cannot be
           generated until the next time-step window, requiring the user to
           wait 30 (or possibly 60) seconds (e.g., if an entry error is made);

       ·   Some devices are difficult to read in low-light conditions;
           presbyopic users and those with impaired vision may have difficulty
           reading the display.


   Accounts
       The accounts managed by dacstoken are completely separate from the
       accounts used by local_passwd_authenticate[21] or any other DACS
       authentication module.

       Accounts for HOTP and TOTP devices may either be combined or kept
       separate. If the virtual filestore item type auth_hotp_token is
       defined, it is only used for accounts associated with HOTP tokens.
       Similarly, if the virtual filestore item type auth_totp_token is
       defined, it is only used for accounts associated with TOTP tokens. If
       either item type is not defined, accounts are accessed through DACS's
       virtual filestore using item type auth_token. It is assumed that file
       permissions on the account databases are such that all access is
       limited to the administrator and local_token_authenticate.

       If accounts for the two device types are combined, because each
       username for an authentication method must be unique, if an individual
       has both types of token they must be assigned different usernames. So,
       for example, if Auggie has one HOTP token and one TOTP token, the
       former might correspond to the username auggie-hotp and the latter to
       auggie-totp; the sign-on form might include a device-mode input which
       would allow Auggie to simply type "auggie" in the username field and
       JavaScript to automatically append the appropriate suffix based on the
       select device mode. An obvious disadvantage of this configuration is
       that it results in two different DACS identities for the same
       individual; this would have to be remembered if an access control rule
       needed to identify Auggie explicitly. If both tokens should map to the
       same DACS identity, the Auth clause could strip the suffix off after
       successful authentication, but the administrator would then need to
       beware of the case of two different Auggies, each using a different
       device type.

       Configuring both the auth_hotp_token and auth_totp_token item types (or
       just one of them and auth_token) keeps the accounts separate and allows
       the same username to be used for both types of devices. Auggie could
       therefore have an account record with the same username for both device
       types. This approach requires the device mode to be specified when an
       operation is requested so that the correct item type can be used; this
       means that users must know which type of device they are using (perhaps
       by afixing a label to it). Refer to important details regarding DACS
       identities[22].

       The -vfs is used to configure or reconfigure the auth_token item type.

       Only keys that meet the minimum key length requirement (16 bytes) may
       be stored with account information (e.g., with -set or -import). In
       other contexts, the requirement is not enforced.

       The secret key is encrypted by dacstoken when it is written to the
       account file. The virtual filestore item type auth_token_keys
       identifies the encryption keys for dacstoken to use; the -inkeys and
       -outkeys flags specify alternatives (see dacskey(1)[23]). If the
       encryption keys are lost, the secret keys are practically
       unrecoverable.

           Important
           If an attacker discovers a secret key, generating usable passwords
           without possessing the token will not be difficult. For at least
           some hardware tokens, the key is burned in to the device and cannot
           be changed; in this case, if the key is leaked the device should be
           destroyed. If a token is lost, the corresponding account should be
           disabled. In the event an attacker finds a lost token or discovers
           a secret key, having a strong PIN associated with the account will
           make it difficult for the attacker to gain access.

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

               ·   Authenex A-Key 3600[24] one-time password (HOTP) hardware
                   token;

               ·   Feitian Technologies[25]OTP C100 and OTP C200 one-time
                   password hardware tokens, provided by HyperSecu Information
                   Systems[26]; and

               ·   OATH Token[27] software application by Archie Cobbs, which
                   implements both HOTP and TOTP on the iPod Touch, iPhone,
                   and iPad[28].

               ·   Feitian Technologies iOATH Lite[29]HOTP software
                   application for the iPod Touch, iPhone, and iPad.

               Other manufacturers interested in having their products
               supported by DACS are welcome to contact Dss.

           ·   Photo[30]: Feitian OTP C200, iPod Touch with the OATH Token
               app, Authenex A-Key 3600 (clockwise from top left)

           ·   Although this implementation should work with similar,
               conformant products, only these products are officially
               supported by DACS.

           ·   Hardware tokens can be purchased directly from the vendors.

           ·   Any problems with using tokens to authenticate through DACS are
               not the responsibility of the token vendor.

   Importing and Exporting OTP Accounts
       Descriptions of accounts and their tokens can be loaded or dumped
       (refer to the -import and -export flags). This simplifies bulk
       provisioning, backup, and portability. The account information is
       written in a simple, application-specific (almost) XML format.

       The format understood by dacstoken consists of a root element
       ("otp_tokens"), followed by zero or more "otp_token" elements, one per
       line, each with required and optional attributes (described below). The
       XML declaration must be omitted. Leading whitespace and blank lines are
       ignored, as are single line XML comments. Additionally, lines having a
       "#" as the first non-whitespace character are ignored. Optional
       attributes that are not present are assigned default values. The
       default digest algorithm is SHA1. Short attribute names are used to
       save space. Unrecognized attributes, and attributes irrelevant to the
       device mode, are ignored. Single or double quote characters (or both)
       within XML attribute values must be replaced by the corresponding
       entity reference ("&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.

       Recognized attributes are:

       ·   b:
             base
             -- radix for OTP value
             [Optional:
             10 (default),
             16, or 32]

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

       ·   d:
             OTP device mode
             -- "c" (for HOTP)
             or "t" (for TOTP)
             [Required]

       ·   dn:
             digest-name
             -- one of the Secure Hash Algorithms
             [Optional:
             SHA1 (default),
             SHA224, SHA256,
             SHA384, SHA512]

       ·   dr:
             clock-drift
             -- clock adjustment, in seconds, for TOTP
             [Optional]

       ·   ek:
             encrypted-key
             -- encrypted secret key, base-64 encoded
             [Required:
             OTP account records only]

       ·   en:
             enabled-status
             -- 1 for enabled,
             0 for disabled
             [Required]

       ·   k:
             plaintext-key
             -- unencrypted secret key
             [Required]

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

       ·   nd:
             ndigits
             -- number of digits for OTP value
             [Optional:
             default is 6 for HOTP,
             8 for TOTP]

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

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

       ·   s:
             serial-number
             -- unique identifier string for the device
             [Required]

       ·   ts:
             time-step
             -- time-step value, in seconds, for TOTP
             [Optional:
             default is 30]

       ·   u:
             username
             -- a valid DACS username associated with this account
             [Required]

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

           <otp_tokens>
           <!-- Staff OTP tokens for DACS authentication -->
           <otp_token u="ietf" d="t" en="1" s="totp-ietf &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"/>
           </otp_tokens>


           Security
           Because imported records include the unencrypted secret keys for
           the OTP devices, the exported file should be kept encrypted (e.g.,
           using openssl) or at least have appropriate file permissions.

           Note
           A standard format for OTP device provisioning is being developed.
           This format may be understood by a future version of dacstoken, or
           a conversion utility may be written. The standard format is likely
           to be considerably more complex than the DACS format.

OPTIONS
       In addition to the standard dacsoptions[1], a lengthy list of command
       line flags are recognized. When a username is given, default values
       associated with that account are used, otherwise recommended or
       implementation-specific defaults are used. These default values can
       usually be overridden on the command line. Some flags are only allowed
       with a particular token mode (e.g., -counter, -totp-show) and their
       appearance implies that mode, making the -mode flag unnecessary; other
       flags are mode independent (e.g., -delete, -enable). It is an error to
       use a mutually incompatible flag combination. Flags that are
       meaningless with the selected operation are ignored, although they
       still imply a mode. Hexadecimal values are case insensitive. If a
       counter value is required but unspecified (e.g., when creating an
       account), an initial counter value of zero is used.

       The op-spec specifies the operation to be performed, together with zero
       or more modifier flags. If op-spec is missing, the -list operation is
       performed. An op-spec is one of the following:

       -auth otp-value
           This flag is like -validate[31], except:

           ·   a username is required, from which all parameters are obtained
               (such as the key);

           ·   if the account has a PIN, it must be provided;

           ·   if the account is for a HOTP token, the counter will be updated
               if authentication is successful.

           An exit status of zero indicates successful authentication, while
           any other value means authentication failed.

       -convert filename
           Load an older format (prior to release 1.4.25) token account file
           from filename ("-" means to read from stdin), convert it to the
           newer format, and write it to stdout (as by -export). This flag is
           deprecated and this capability will be removed in a future release
           of DACS.

       -create
           Create an account for username, which must not already exist. In
           other respects it works like -set[32]. When creating a new account,
           -serial is required and -key is implied. If no -enable flag is
           provided when creating an account, -disable is implied. If no
           -counter flag is provided, a default of zero is used. If one of the
           PIN flags is present, the given PIN will be assigned to the
           account, otherwise the account will not have a PIN (or the existing
           PIN will not be changed).

       -current
           Display the current moving factor (i.e., the counter value for HOTP
           or the interval value for TOTP) and expected OTP for username. For
           HOTP, the counter is advanced. All parameters are taken from the
           account.

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

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

       -export
           Write information about all accounts, or only one account if
           username is given, to stdout. If a mode is selected, however, only
           accounts having that mode will be written. This information may be
           reloaded using -import or -import-replace. The output should be
           stored in an encrypted form, or at the very least have its file
           permissions set appropriately. For example:

               % dacstoken -uj EXAMPLE -export | openssl enc -aes-256-cbc > dacstoken-exported.enc

           Later, you might do something like:

               % openssl enc -d -aes-256-cbc < dacstoken-exported.enc | dacstoken -uj EXAMPLE -import -


       -h
       -help
           Display a help message and exit.

       -hotp-show num
           Display num consecutive HOTP passwords from a given counter value
           and key. The -counter flag can be used to specify an initial
           counter value. The key can be specified using -key, -key-file, or
           -key-prompt. If a username is provided, the initial counter value
           and key are obtained from the user's HOTP account, unless either
           value is overridden on the command line; the account's stored
           counter value is not modified. This is mainly intended for
           debugging purposes.

       -import filename
       -import-replace filename
           Load account and token information from filename; if filename is
           "-", stdin is read. If a mode is selected, only accounts having
           that mode will be read. With -import it is an error if an imported
           account already exists, and processing stops; -import-replace will
           replace an existing account with imported data.

       -l
       -list
       -long
           If username is provided, display information about the
           corresponding account; if the -serial flag is given, display
           information about the account with the specified serial number;
           otherwise list all accounts. If the -mode flag is given in any of
           these cases, however, list only those accounts that have the
           operational mode specified. If this flag is repeated, or with the
           -long flag, more detail is displayed: device type, account status,
           device serial number, counter value (for HOTP), clock drift value
           (for TOTP), whether or not the account has a PIN (indicated by a
           "+" or "-" symbol), and the time and date of the account's last
           modification.

       -rename new-username
           Rename the existing account for username to be new-username, and
           modify the new account using command line arguments (as with
           -set[32]). As this requires two steps that are not done atomically,
           if an error occurs it is possible for the new account to be created
           and the old account to still exist.

       -set
           The -set flag is used to modify the existing account for username
           based on one or more modifier arguments (-base, -counter, -digits,
           -disable or -enable, -key (or -key-file or -key-prompt), -pin (or
           -pin-file or -pin-prompt), or -serial). The mode can also be
           changed by specifying -mode, but mode-specific parameters
           associated with the account will be lost (e.g., the current counter
           value will be deleted if a HOTP account is changed to a TOTP
           account) and general parameters (such as the serial number) will be
           retained unless overridden on the command line.

       -sync password-list
           In HOTP mode, this attempts to synchronize the server with the
           token for username. The password-list is a comma-separated list of
           three successive passwords produced by the user's token (this
           "auto-synchronize" function is also available through
           local_token_authenticate[3]). The given sequence must match the
           computed sequence exactly, given the operational parameters in
           effect; e.g., leading zeroes are significant, as is the display
           radix and number of OTP digits in effect. If synchronization is
           successful, the user should be able to authenticate using the next
           password produced by the device. An exhaustive search algorithm
           using increasing counter values is employed, with a compile-time
           limit on the maximum number of computations. The search begins at
           the server's currently stored counter value, unless one is provided
           using -counter. If unsuccessful, this operation could take a long
           time before it terminates; the user must contact an administrator
           for assistance.

           In TOTP mode, attempt to determine how closely synchronized the
           system clock is with the token's clock and display the result. This
           information can be used to update the user's token record to
           compensate for poorly synchronized clocks, or to adjust validation
           parameters. The token's key and the name of the digest algorithm
           are obtained for the token record belonging to username, if it is
           given; otherwise the key is prompted for and the digest algorithm
           to use is either obtained from the command line or the default.
           Only the first password in password-list is used. The
           -totp-timestep, -digits, and -totp-base options are effective
           during this operation.

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

       -totp-show num
           Display a sequence of TOTP passwords using the parameters currently
           in effect: interval size (-totp-timestep), number of digits
           (-digits), and base (-base). The account's stored parameters are
           not modified. This is mainly intended for debugging purposes.

           If a username is provided (it must be associated with a TOTP
           device), the key and other stored parameters from the account are
           used unless overridden by command line flags. The sequence of
           passwords for num intervals before and after the current time,
           together with the password for the current time are printed.

           If no username is given, the program prompts for the key (which is
           echoed) and uses command line flags or default values for
           parameters. It then emits the TOTP password for the current time
           each time Return/Enter is pressed. Typing EOF causes immediate
           termination.

       -validate otp-value
           If otp-value is the next expected one-time password, return an exit
           status of zero to indicate success; any other value indicates
           failure. If username is given, parameters for validation, including
           the key, are obtained from that account unless overridden on the
           command line. The server's state is not changed; e.g., a HOTP
           counter is not advanced. If no username is given, the -mode flag
           must be used and the parameters required for that mode must be
           given, including a key. For HOTP mode, a counter value must be
           provided. For TOTP mode, command line parameters are effective
           during this validation.  dacstoken will test whether otp-value
           validates against the parameters in effect.

       The following modifier flags are understood:

       -all
           With -set and no username, apply the changes to all accounts. This
           can be used to enable or disable all accounts, for example. The
           -inkeys and -outkeys flags are honoured. If an error occurs
           processing stops immediately, in which case only some accounts may
           have been modified.

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

       -counter num
           This is the 8-byte HOTP counter value to set, expressed as a hex
           value if preceded by by "0x" (or "0X"), decimal otherwise. Leading
           zeroes may be elided. This implies HOTP mode. For token devices, it
           should not be possible to reset a counter (modulo counter overflow)
           because that will result in the password sequence being repeated,
           assuming that the key is not changed; software implementations
           might not have this restriction, however, so beware of the security
           implications.

       -digits num
           Use num digits when displaying an OTP. The value of num is
           restricted to 6, 7, 8 (the default), or 9 with base 10. It is
           restricted to 6 with base 32 and is ignored with base 16 (hex
           output).

       -disable
           Disable the account for username. The local_token_authenticate
           module, and -auth and -validate flags, will not allow the user to
           authenticate until the account has been enabled, although other
           operations may still be performed on the account. If -enable is
           subsequently used, the account will become usable for
           authentication and is restored to its state at the time it was
           disabled. It is not an error to disable an already disabled
           account.

       -enable
           Enable the account for username. The local_token_authenticate
           module will allow the user to authenticate. It is not an error to
           enable an already enabled account.

       -hotp-window num
           If the expected HOTP password does not match the given password,
           try to match up to num passwords after the expected password in the
           sequence. A value of zero for num disables this search.

       -inkeys item_type
           For decrypting secret keys, use the store identified by item_type,
           presumably configured in dacs.conf.

       -key keyval
           Use keyval as the secret key, expressed as a hex digit string.

               Security
               Supplying a key on the command line is not secure because it
               may be visible to other processes.

       -key-file filename
           Read the secret key, expressed as a hex digit string, from
           filename. If filename is "-", the key is read from stdin.

       -key-prompt
           Prompt for the secret key, expressed as a hex digit string. The
           input is not echoed.

       -mode otp-mode
           This specifies (case insensitively) the type of token (the OTP
           device mode) for use with -set, -create, and validation and
           synchronization operations. The otp-mode may be either counter or
           hotp for counter mode, or time or totp for time-based mode. This
           flag is required when creating a new account.

       -outkeys item_type
           For encrypting secret keys, use the store identified by item_type,
           presumably defined in dacs.conf.

       -pin pinval
           Use pinval as the secret PIN for the account.

               Security
               Supplying a PIN on the command line is not secure because it
               may be visible to other processes.

       -pin-constraints str
           Instead of using PASSWORD_CONSTRAINTS[14], use str (having the same
           syntax and semantics) to describe the requirements for a PIN.

               Note
               Requirements for a PIN apply to PINs obtained via a command
               line flag and to those obtained through importing (using the
               "p" attribute). Requirements are not "retroactive", however, so
               changing the requirements does not affect the PINs of existing
               accounts or importing accounts that were previously exported
               (having a "ph" attribute).

       -pin-file filename
           Read the secret PIN from filename. If filename is "-", the PIN is
           read from stdin.

       -pin-prompt
           Prompt for the secret PIN. The input is not echoed.

       -rnd
           Reserved for future use.

       -seed str
           Reserved for future use.

       -serial str
           The serial number, str, is a (purportedly) unique identifier
           assigned to the token. This option is used with the -set, -create,
           and -list flags. A serial number identifies a specific OTP device
           and need not be kept secret. The uniqueness property is enforced
           within an item type storage unit; that is, serial numbers of all
           HOTP devices must be unique, serial numbers of all TOTP devices
           must be unique, and if accounts for the two device types are
           combined, all device serial numbers must be unique. Any printable
           string is accepted. If a software client is generating passwords,
           you may use the device's serial number, or choose any suitably
           descriptive string not already assigned to a device.

               Note
               A jurisdiction that allows (or may eventually allow) both
               hardware tokens and software-generating client applications
               should consider adopting a formalized naming scheme for its
               tokens. For example, the administrator might append "-hw" to
               the vendor's serial number to form the dacstoken serial number.
               For software tokens, the administrator might create a dacstoken
               serial number by appending "-sw" to the vendor's serial number
               for the device.

       -totp-delta num
           Adjust the base time by num intervals (each of the step size number
           of seconds) when computing a TOTP. The num may be negative, zero,
           or positive. This is used to correct for inadequately synchronized
           clocks.

       -totp-drift nwindows
           For TOTP, use a window size of nwindows (in terms of the interval
           size) for validation. If nwindows is 0, the computed TOTP value
           must match the given one exactly. If nwindows is 1, for example,
           dacstoken will try to match the given TOTP value in the previous,
           current, and next intervals. This allows the clocks in the system
           running dacstoken (or local_token_authenticate) and token producing
           device to be less well synchronized.

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

       -totp-hash alg
           Use alg as the digest algorithm with TOTP. The value of alg is
           restricted to (case insensitively) SHA1 (the default), SHA256, or
           SHA512.

       -totp-timestep secs
           Use secs as the interval size when computing a TOTP. It must be
           greater than zero. The default is 30 seconds.

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

       -vfs vfs_uri
           Use vfs_uri to override the VFS[33] configuration directive in
           effect. This can be used to configure or reconfigure auth_token,
           auth_hotp_token, or auth_totp_token to specify the storage method
           for the accounts being acted upon.

       Apart from error messages, which are printed to the standard error, all
       output goes to the standard output.

       Ordinarily, a dacsoption will be specified to select the jurisdiction
       on behalf of which accounts are being managed.

EXAMPLES
       These examples assume that the jurisdiction name to use is EXAMPLE and
       its federation domain is example.com.

       To use this authentication method, a DACS administrator might perform
       the following steps for each OTP device assigned to a user:

        1. Obtain a supported token, review how it is used for authentication,
           and select values for the various parameters. Obtain the secret key
           for the device from the vendor; for a programmable device, select a
           suitable random key and program it into the device. The current
           counter values might also be obtained from the vendor, although it
           is likely to initialized to zero; for a programmable device, set
           the counter value to zero. Decide whether a PIN will be required
           (see TOKEN_REQUIRES_PIN[9]). If a software client is being used,
           install the software on the user's device (or have the user do so),
           and configure the software.

        2. Decide where the account information will be stored and, if
           necessary, add a suitable VFS[33] directive to dacs.conf. The
           default (found in site.conf) maintains the account information in a
           file named auth_tokens within each jurisdiction's default private
           area:

               VFS "[auth_token]dacs-kwv-fs:${Conf::FEDERATIONS_ROOT}/\
               ${Conf::FEDERATION_DOMAIN}/${Conf::JURISDICTION_NAME}/auth_tokens"


        3. Generate keys to encrypt the account information (see Tokens and
           secret keys[34]) and decide where they will be stored; for example
           (your user ID, group ID, path, jurisdiction name, and federation
           domain may vary):

               % cd /usr/local/dacs/federations_root/example.com/EXAMPLE
               % dacskey -uj EXAMPLE -q auth_token_keys
               % chgrp www auth_token_keys
               % chmod 0640 auth_token_keys

           If necessary, add a suitable VFS[33] directive to dacs.conf; the
           default, which is used above, maintains the account information in
           a file named auth_token_keys within each jurisdiction's default
           private area:

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


        4. If you need users to sign on through dacs_authenticate(8)[2], you
           must configure a suitable Auth clause in dacs.conf, for example:

               <Auth id="token">
                 URL "token"
                 STYLE "pass"
                 CONTROL "sufficient"
               </Auth>


        5. There are several ways that an administrator might proceed,
           depending on how much of the effort can be done by users (e.g.,
           whether they can be trusted, their technical ability), how many
           users there are (a few, or thousands), and the level of security
           required.

            1. prepare a file containing an XML record[35] for each account to
               be created; if PINs are to be used, assign a random PIN to each
               account;

            2. use the -import[36] flag to create the accounts;

            3. give the token device, username, and (if necessary) initial PIN
               to the user (perhaps verifying identity), providing any
               necessary demonstration and instructions;

            4. have the user set or reset the PIN for the account, and ask the
               user to sign on using the token to confirm correct operation.


       To create a disabled account for user bobo for a HOTP device:

           % dacstoken -uj EXAMPLE -mode hotp -serial 37000752 -key-file bobo.key -create bobo

       The secret key for the account (which must not already exist) is read
       from the file bobo.key. New accounts are disabled by default; use
       -enable to create an enabled account.

       Once an account has been created, it can be synchronized with the
       token. To synchronize the HOTP token for user bobo:

           % dacstoken -uj EXAMPLE -sync 433268,894121,615120 bobo

       In this example, the particular token produced the three consecutive
       passwords 433268, 894121, and 615120. Note that the password sequence
       string that follows the -sync flag is a single argument that cannot
       have any embedded spaces. If the key for this token is
       19c0a3519a89b4a8034c5b9306db, the next password generated by this token
       should be 544323 (with counter value 13). This can be verified using
       -hotp-show:

           % dacstoken -hotp-show 5 -counter 10 -key 19c0a3519a89b4a8034c5b9306db
           000000000000000a: 433268
           000000000000000b: 894121
           000000000000000c: 615120
           000000000000000d: 544323
           000000000000000e: 002442

       To enable the account for user bobo:

           % dacstoken -uj EXAMPLE -enable -set bobo

       To both set the PIN and enable the account for user bobo:

           % dacstoken -uj EXAMPLE -enable -pin "CzAy" -set bobo

       To list all accounts in detail:

           % dacstoken -uj EXAMPLE -long

       The -list flag is redundant because it is the default operation. The
       -mode, -counter, etc. modifiers have no effect when listing.

       To list only the account for bobo:

           % dacstoken -uj EXAMPLE -list bobo

       The exit status will be non-zero if this user does not have an account.

       To display the account for the device with serial number 37000752:

           % dacstoken -uj EXAMPLE -serial 37000752

       The serial number, which should uniquely identify a token, is often
       printed on the token or can be displayed by the token.

       To set the counter value for the existing account of bobo:

           % dacstoken -uj EXAMPLE -counter 9 -set bobo

       This operation might be used for testing or with a software token. The
       -sync operation is more appropriate for a hardware token.

       To change the PIN for username bobo:

           % dacstoken -uj EXAMPLE -pin-prompt -set bobo

       The program will prompt for the new PIN.

       To use an alternate account file, /secure/auth_tokens:

           % dacstoken -uj EXAMPLE -vfs "dacs-kwv-fs:/secure/auth_tokens" -list

       To use new keys (making the same assumptions as earlier), add a
       suitable VFS directive to dacs.conf; the default defines the item type
       auth_token_keys_prev as follows:

           VFS "[auth_token_keys_prev]dacs-fs:${Conf::FEDERATIONS_ROOT}/\
           ${Conf::FEDERATION_DOMAIN}/${Conf::JURISDICTION_NAME}/auth_token_keys.prev"

           % cd /usr/local/dacs/federations_root/example.com/EXAMPLE
           % mv auth_token_keys auth_token_keys.prev
           % dacskey -uj EXAMPLE -q auth_token_keys
           % chgrp www auth_token_keys
           % chmod 0640 auth_token_keys
           % dacstoken -uj EXAMPLE -inkeys auth_token_keys.prev -set


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

BUGS
       HOTP should probably be called COTP, but HOTP came before TOTP.  WOTP?

       Listings may only be sorted by username.

       The drift adjustment for TOTP accounts is tied to the real time clocks
       of a particular client/server pair. If either clock is effectively
       changed "too much" (e.g., by resetting a very fast server clock or
       replacing an old token that had a relatively slower clock), then a user
       will observe the token to suddenly stop working. Resynchronization is
       required in these cases. Sharing an account file amongst two or more
       servers should be avoided in general (because locks are unlikely to be
       visible across hosts), but also if their clocks are not always well
       synchronized. It is recommended that the Network Time Protocol (RFC
       1305[37]) or equivalent be used on any host that runs DACS commands or
       web services.

       The implementation of time-based tokens is based on the latest
       available Internet-Draft, which is considered by the IETF to be a "work
       in progress". Hence the algorithm, its implementation (including DACS
       accounts based on this operational mode), and documentation are all
       subject to change.

       TOTP password matching windows are symmetrical.

       This functionality should probably be available through
       dacs_admin(8)[38] and dacsauth(1)[39], but it's not.

       Mutual authentication using tokens should be implemented.

       Although release 1.4.25 introduced many improvements, some cause
       incompatibilities with earlier versions of dacstoken.

SEE ALSO
       RFC 4226[4], draft-mraihi-totp-timebased-05.txt[5],
       dacs_authenticate(8)[2], dacs_token(8)[8], dacsgrid(1)[40],
       dacspasswd(1)[10], opie(4)[41], Mobile One Time Passwords[42],
       mod_authn_otp[43]

AUTHOR
       Distributed Systems Software (www.dss.ca[44])

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

COPYING
       Copyright2003-2013 Distributed Systems Software. See the LICENSE[45]
       file that accompanies the distribution for licensing information.

NOTES
        1. dacsoptions
           http://dacs.dss.ca/man/dacs.1.html#dacsoptions

        2. dacs_authenticate
           http://dacs.dss.ca/man/dacs_authenticate.8.html

        3. local_token_authenticate
           http://dacs.dss.ca/man/dacs_authenticate.8.html#token

        4. RFC 4226
           http://www.rfc-editor.org/rfc/rfc4226.txt

        5. latest IETF Internet-Draft
           http://www.ietf.org/id/draft-mraihi-totp-timebased-05.txt

        6. Additional operational modes
           http://www.ietf.org/id/draft-mraihi-mutual-oath-hotp-variants-11.txt

        7. -convert flag
           http://dacs.dss.ca/man/#convert_flag

        8. dacs_token(8)
           http://dacs.dss.ca/man/dacs_token.8.html

        9. TOKEN_REQUIRES_PIN
           http://dacs.dss.ca/man/dacs.conf.5.html#TOKEN_REQUIRES_PIN

       10. dacspasswd(1)
           http://dacs.dss.ca/man/dacspasswd.1.html

       11. dacs_passwd(8)
           http://dacs.dss.ca/man/dacs_passwd.8.html

       12. PASSWORD_DIGEST
           http://dacs.dss.ca/man/dacs.conf.5.html#PASSWORD_DIGEST

       13. PASSWORD_SALT_PREFIX
           http://dacs.dss.ca/man/dacs.conf.5.html#PASSWORD_SALT_PREFIX

       14. PASSWORD_CONSTRAINTS
           http://dacs.dss.ca/man/dacs.conf.5.html#PASSWORD_CONSTRAINTS

       15. RFC 2104
           http://www.rfc-editor.org/rfc/rfc2104.txt

       16. FIPS 198
           http://csrc.nist.gov/publications/fips/fips198/fips-198a.pdf

       17. time(3)
           http://www.freebsd.org/cgi/man.cgi?query=time&apropos=0&sektion=3&manpath=FreeBSD+9.1-RELEASE&format=html

       18. dacsexpr(1)
           http://dacs.dss.ca/man/dacsexpr.1.html

       19. man-in-the-middle attack
           http://en.wikipedia.org/wiki/Man-in-the-middle_attack

       20. revocation list
           http://dacs.dss.ca/man/dacs.acls.5.html#revocation_list

       21. local_passwd_authenticate
           http://dacs.dss.ca/man/dacs_authenticate.8.html#passwd

       22. DACS identities
           http://dacs.dss.ca/man/dacs.1.html#gloss_identity

       23. dacskey(1)
           http://dacs.dss.ca/man/dacskey.1.html

       24. Authenex A-Key 3600
           http://www.authenex.com

       25. Feitian Technologies
           http://www.ftSafe.com

       26. HyperSecu Information Systems
           http://www.hypersecu.com

       27. OATH Token
           http://oathtoken.googlecode.com

       28. iPod Touch, iPhone, and iPad
           http://itunes.apple.com/us/app/oath-token/id364017137?mt=8

       29. iOATH Lite
           http://itunes.apple.com/ca/app/ioath-lite/id327109243?mt=8

       30. Photo
           http://dacs.dss.ca/otp-tokens2.jpg

       31. -validate
           http://dacs.dss.ca/man/#validate_flag

       32. -set
           http://dacs.dss.ca/man/#set_flag

       33. VFS
           http://dacs.dss.ca/man/dacs.conf.5.html#VFS

       34. Tokens and secret keys
           http://dacs.dss.ca/man/#security1

       35. XML record
           http://dacs.dss.ca/man/#user_provisioning

       36. -import
           http://dacs.dss.ca/man/import_flag

       37. RFC 1305
           http://www.rfc-editor.org/rfc/rfc1305.txt

       38. dacs_admin(8)
           http://dacs.dss.ca/man/dacs_admin.8.html

       39. dacsauth(1)
           http://dacs.dss.ca/man/dacsauth.1.html

       40. dacsgrid(1)
           http://dacs.dss.ca/man/dacsgrid.1.html

       41. opie(4)
           http://www.freebsd.org/cgi/man.cgi?query=opie&apropos=0&sektion=4&manpath=FreeBSD+9.1-RELEASE&format=html

       42. Mobile One Time Passwords
           http://motp.sourceforge.net

       43. mod_authn_otp
           http://code.google.com/p/mod-authn-otp

       44. www.dss.ca
           http://www.dss.ca

       45. LICENSE
           http://dacs.dss.ca/man/../misc/LICENSE



DACS 1.4.28b                      02/04/2014                      DACSTOKEN(1)