---
name: "dacs_token"
section: "8"
platform: "linux"
package: "dacs"
version: "1.4.40-2"
release: "Debian 10 (Buster)"
platforms: ["linux"]
url: "https://new.carta.tech/dacs_token"
---

# dacs\_token(8)

manage DACS one-time password token accounts

## NAME

dacs\_token - manage DACS one-time password token accounts

## SYNOPSIS

**dacs\_token** \[**dacsoptions**\[1\]\]

## DESCRIPTION

This program is part of the **DACS** suite.

The **dacs\_token** web service provides limited account management operations on accounts recognized by **local\_token\_authenticate**\[2\], a **DACS** authentication module. Full administrative functionality is provided by **dacstoken**; refer to **[dacstoken(1)](/dacstoken/1.md)**\[3\] for detailed information about one-time passwords, token devices, and user accounts. These accounts are completely separate from any other accounts and passwords.

Subject to configuration and valid authorization, this web service lets:

• users set an initial PIN for their account (note that his presents a window of opportunity for an attacker that has obtained a PIN-less token);

• users change the PIN on their account;

• users synchronize their account with their token; and

• **DACS** administrators (see **ADMIN\_IDENTITY**\[4\]) set, change, or remove the PIN on any account, synchronize an account with a token (removal depends on **TOKEN\_REQUIRES\_PIN**\[5\]), or obtain the next OTP for a specified account;

• anyone create and test a demonstration account (visit **dacs.dss.ca**\[6\] to try a live demonstration).

Outside of demonstration mode operation, accounts are managed identically to **[dacstoken(1)](/dacstoken/1.md)**\[3\] using the item types auth\_token, auth\_hotp\_token, and auth\_totp\_token.

**Security**\

The same account security stipulations as **dacstoken** apply.

The web service applies access controls internally; a **DACS** ACL can be added to further restrict its use. The internal rules are:

• A **DACS** administrator can synchronize any account without providing the account's PIN; other users must provide the account's PIN, if there is one.

• A **DACS** administrator can set, change, or remove (depending on **TOKEN\_REQUIRES\_PIN**\[5\]) any account's PIN; other users can set or change their account's PIN by:

• authenticating as the username of the account being accessed (if the account has a PIN and the user has forgotten it, presumably a different authentication method must be used); or

• contacting a **DACS** administrator.

• Demonstration mode is enabled if the item type auth\_token\_demo is defined; otherwise, if auth\_token\_hotp\_demo is defined, then demonstration mode for HOTP is enabled, and if auth\_token\_totp\_demo is defined, then demonstration mode for TOTP is enabled. If none of these item types is enabled, which is the default, then demonstration mode is inoperative.

When validating a HOTP one-time password, the **TOKEN\_HOTP\_ACCEPT\_WINDOW**\[7\] configuration directive can be used to allow an account's counter value to automatically "catch up" to the token's.

## OPTIONS

### Web Service Arguments

In addition to the **standard CGI arguments**\[8\], **dacs\_token** understands the following CGI arguments:

*CONFIRM\_NEW\_PIN*

Required with the SET\_PIN operation, the value of this argument must be the same as the value of *CONFIRM\_NEW\_PIN*.

*OPERATION*

The following operations are supported:

• CURRENT

Unlike the other operations, this operation returns a text/plain MIME type, consisting of the current *moving factor* (i.e., the HOTP counter value or the TOTP interval value), followed by a space and the corresponding OTP for *USERNAME*. This facilitates an easy-to-use, REST-type interface. In the case of HOTP, the counter value is advanced, "consuming" the OTP. Only an administrator is allowed to perform this operation, which can be used to build a simple mutual authentication capability:

 1\. The user gives a username to the sign-on procedure;

 2\. The sign-on procedure asks **DACS** for the OTP it expects the user's token to produce, based on the user's account parameters;

 3\. The sign-on procedure presents the OTP to the user, who verifies its correctness by matching the presented OTP with the one actually produced by the token;

 4\. The user continues the authentication procedure, perhaps by providing the token's next OTP or using another authentication method, such as a password.

The appropriateness of TOTP mode for mutual authentication depends on the OTP lifetime and other configuration parameters.

• SET\_PIN

Set or change the PIN associated with the account for *USERNAME*. This operation requires the *NEW\_PIN*, *CONFIRM\_NEW\_PIN*, *MODE*, and *USERNAME* arguments.

• SYNC

Synchronize the account for *USERNAME* so that the next password produced by the token is expected to be valid. This operation requires the *PASSWORD*, *MODE*, and *USERNAME* arguments.

• DEMO\_CREATE

Create a demonstration account according to the given arguments, configuration values, and defaults. Required arguments: *MODE*, *KEY*, *KEY\_ENCODING*. Optional arguments: *NEW\_PIN*, *CONFIRM\_NEW\_PIN*, *NDIGITS*, *BASE*, *SERIAL*. Optional HOTP argument: *COUNTER*. Optional TOTP arguments: *DIGEST\_NAME*, *TIME\_STEP*. The *KEY\_ENCODING* argument, which indicates how the *KEY* string has been encoded, must be one of hex, base32, or none.

• DEMO\_SYNC

Synchronize a demonstration account using *USERNAME*, a one-time password or password sequence (*SYNC*), and optional *PIN*.

• DEMO\_VALIDATE

Validate the given demonstration account (*USERNAME*), one-time password (*PASSWORD*), and PIN (*PIN*) in demonstration mode. No credentials are actually issued.

*MODE*

This argument is the device mode, which may be (case insensitively) counter or hotp for counter mode, or time or totp for time-based mode.

*NEW\_PIN*

With the SET\_PIN operation, this is the new PIN to associate with the account. An administrator can remove the PIN entirely, provided it is allowed by **TOKEN\_REQUIRES\_PIN**\[5\], by omitting (or not providing a value for) both *NEW\_PIN* and *CONFIRM\_NEW\_PIN*.

*PASSWORD*

If the request is not accompanied by credentials for *USERNAME* or an administrator identity, this one-time password must validate against the expected value for *USERNAME*.

*PIN*

*USERNAME*

The **DACS** username of interest.

## DIAGNOSTICS

The program exits 0 if everything was fine, 1 if an error occurred.

## BUGS

This version only provides self-service operations for users and limited account management for a **DACS** administrator; administrators must use **[dacstoken(1)](/dacstoken/1.md)**\[3\] for everything else. Full-blown web-based token account management should either be provided by **dacs\_token** or **[dacs\_admin(8)](/dacs_admin/8.md)**\[9\].

Demonstration mode accounts should be manually deleted from time to time.

The *FORMAT* is not understood. XML responses should be implemented.

## SEE ALSO

**[dacstoken(1)](/dacstoken/1.md)**\[3\], **[dacs.conf(5)](/dacs.conf/5.md)**\[10\], **[dacs\_authenticate(8)](/dacs_authenticate/8.md)**\[11\]. Also see the OTP token demonstration, token\_demo.html.

## AUTHOR

Distributed Systems Software (**www.dss.ca**\[12\])

## COPYING

Copyright © 2003-2015 Distributed Systems Software. See the **LICENSE**\[13\] file that accompanies the distribution for licensing information.

## NOTES

- 1\.

  dacsoptions

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

- 2\.

  local\_token\_authenticate

  http://dacs.dss.ca/man/dacs\_authenticate.8.html#local\_token\_authenticate

- 3\.

  [dacstoken(1)](/dacstoken/1.md)

  http://dacs.dss.ca/man/dacstoken.1.html

- 4\.

  ADMIN\_IDENTITY

  http://dacs.dss.ca/man/dacs.conf.5.html#ADMIN\_IDENTITY

- 5\.

  TOKEN\_REQUIRES\_PIN

  http://dacs.dss.ca/man/dacs.conf.5.html#TOKEN\_REQUIRES\_PIN

- 6\.

  dacs.dss.ca

  http://dacs.dss.ca

- 7\.

  TOKEN\_HOTP\_ACCEPT\_WINDOW

  http://dacs.dss.ca/man/dacs.conf.5.html#TOKEN\_HOTP\_ACCEPT\_WINDOW

- 8\.

  standard CGI arguments

  http://dacs.dss.ca/man/dacs.services.8.html#standard\_cgi\_args

- 9\.

  [dacs\_admin(8)](/dacs_admin/8.md)

  http://dacs.dss.ca/man/dacs\_admin.8.html

- 10\.

  [dacs.conf(5)](/dacs.conf/5.md)

  http://dacs.dss.ca/man/dacs.conf.5.html

- 11\.

  [dacs\_authenticate(8)](/dacs_authenticate/8.md)

  http://dacs.dss.ca/man/dacs\_authenticate.8.html

- 12\.

  www.dss.ca

  http://www.dss.ca

- 13\.

  LICENSE

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