Tools

Tools for FIDO keys

Token2 T2F2 OTP Cli tool

Name: Token2 C301-i programmable hardware token for Office 365 and Azure MFA
Brand: Token2
SKU: t2-51
Price: 21 EUR
Availability: InStock
Rating: 5 (4752 reviews)

Manage and use TOTP/HOTP codes via Python CLI script using a PC/SC device (USB NFC) or directly via USB. A cross-platform solution that has been tested under Windows, macOS and Linux platforms. Python-based tools are essential not only for their cross-platform compatibility, but also because their source-available nature allows experts/developers to examine the source code, ensuring transparency and minimizing the risk of hidden vulnerabilities or malicious elements.

1. Requirements

Please note that this tool works only with our keys with TOTP support (second generation). The keys with HOTP only are not supported. Moreover, HOTP via HID functionality is not supported on some models, such as Bio2 or NFC-Card.

Linux

Create udev rules to allow the access to the token without sudo:

SUBSYSTEM=="usb", ATTR{idVendor}=="349e", ATTR{idProduct}=="0022", MODE="0660", GROUP="plugdev", TAG+="uaccess", TAG+="udev-acl"

Reload udev:

sudo udevadm control --reload-rules && sudo udevadm trigger

Install dependencies:

sudo apt-get update 
sudo apt-get install -y swig build-essential libpcsclite-dev pcscd

Optional (for running the GUI Wrapper, TOTP Viewer):

sudo apt-get install python3-tk
sudo apt-get install xclip

MacOS

Homebrew (brew) package manager is required.
```
 brew install swig 
```
Optional (for GUI Wrapper)
```
 brew install python3-tk 
```

⚠️ Recent changes in the way MacOS handles USB peripherals could impact the stability of our tool under this platform. We're actively working to address this and appreciate your understanding

Windows

No special setup required.

Depending on the system configuration, you may need to use python instead of python3 when launching the script.

2. Installation

Create a virtual environment and install script's required packages inside it:

python3 -m venv venv
source venv/bin/activate
pip3 install -r requirements.txt

The instructions are similar for each platform, but there may be some minor differences, i.e. for Windows, you need to launch activate.bat to activate the virtual environment

3. Usage

Please plug the token using one of the available interfaces:
- NFC: Please plug your PC/SC (USB NFC) reader and ensure to have the recent drivers installed.
- USB: Please plug the token to the USB port of your computer.
Please invoke the script to get usage help.

python3 app.py --help

This will show the output below:

Token2 HOTP/TOTP CLI Tool

positional arguments:
  {set_btn_seed,delete_btn_seed,get_all,read_entry,write_entry,delete_entry,erase_all}
                        command to be executed.
    read_serial_no      read device's serial number
    set_btn_seed        set the seed of HOTP generator triggered by button press
    delete_btn_seed     delete the seed of HOTP generator triggered by button press
    get_all             get all OTP entries
    read_entry          read a particular OTP entry
    write_entry         write or update an OTP entry on the token
    delete_entry        delete OTP entry on the token
    erase_all           erase all OTP entries on the token

options:
  -h, --help            show this help message and exit

Note for MacOS: You might need to invoke the script with sudo in case of device access problems (OSError). Also, it was observed that the script works a lot more stable via NFC than via USB

4. Available commands

Read all OTP entries

Read all OTP entries on the token. In case of all HOTP entries or entries with the "button required" flag set, the code will not be available, although it could be requested with "read single OTP entry" command.

python3 app.py get_all

Read a single OTP entry

Read a particular OTP entry on the token. If the token is connected using USB transport and an entry is a HOTP or has a "button required" flag, the command will hang until the physical button is manually pressed on the token.

python3 app.py read_entry --app-name "Test app" --account-name "Test account"

Get the serial number of the key

Obtains the serial number of the security key. Please note that only PIN+ series keys have the serial number printed on the plastic case.

python3 app.py read_serial_no

Write or update OTP entry

Create a new OTP entry on the token. If there is already an entry which matches both application and account name, that existing entry will be overriden with the new configuration.

python3  app.py write_entry --app-name "Test app" --account-name "Test account"  --seed JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP

python3 app.py write_entry --type TOTP --algorithm SHA1 --timestep 30 --code-length 6 --button-required --app-name "Test app" --account-name "Test account" --seed JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP

This command uses the following parameters:
--algorithm SHA1 or SHA256
--timestep 30 or 60 (time step in seconds)
--code-length 4, 6 or 8 (the length of OTP)
--button-required defines whether the button on the device is required to be pressed/touched to show the OTP (does not apply to NFC transport)
--app-name the name of the app/service (used to identify the OTP profile)
--account-name the name of the account (used to identify the OTP profile)
--seed the TOTP seed in base32 format

Delete OTP entry

Delete a particular OTP entry identified by the application name and account name.

python3 app.py delete_entry --app-name "Test app" --account-name "Test account"

Erase all OTP entries

Delete all existing entries on the token. This will permanently delete all seeds that are currently stored on your token.

python3 app.py erase_all

HOTP via HID (keyboard emulation)

The HOTP via HID functionality described below is not supported on some models, such as Bio2 or NFC-Card.

Configure HOTP function when the physical button is pressed

python3 app.py set_btn_seed --code-length 6 --seed ABCABCAA --short-touch

If you need the OTP to be sent via HID without emulating the Enter keystroke, add --dont-send-enter argument. For cases where numeric keyboard use is required (such as with AZETY keyboards), the --numeric-keyboard can be added.