Python version of the NFC Burner app - token2_config.py

We have been receiving numerous requests from our customers, urging us to make the NFC Burner tools available on both macOS and Linux. To address this demand, we opted for a cross-platform solution, and our choice was to implement it using Python.

This approach allowed us to create a versatile solution that is compatible with a wide range of operating systems, including Linux, macOS, and Windows. The tool is designed to facilitate the process of burning a seed and configuring various options, such as hash type, system clock settings, and time offsets.

We've also provided a straightforward graphical user interface (GUI) for the script, making it more accessible and user-friendly.



token2_config.py is a solution developed by Token2 to program and configure the second generation NFC-programmable single-profile TOTP hardware tokens using nfcpy python library. It works under Linux, macOS and Windows.

Hardware requirements

We have used nfcpy library to implement the solution. Unfortunately, nfcpy only works with a limited number of NFC Reader/writer devices, therefore the existing NFC Writer device used for our Windows applications cannot be used. While our hardware R&D team is till working on creating a nfcpy-compatible driver for our NFC Writer device, we managed to source a batch of nfcpy compatible NFC writer devices based on PN533 chip from NXP/ST-Ericcson which you have to purchase to be able to use this script. PN533 is supported by nfcpy and works flawlessly under any platform.

One of the prerequisites for this script to run is having the nfcpy library correctly installed and running (and nfcpy, in its turn, has its own dependencies, such as libusb). You can check if the library is working fine by running the command below in your python environment:
python -m nfc
The output should be without errors and similar to below:
This is the latest version of nfcpy run in Python 2.7.12
on Linux-4.4.0-47-generic-x86_64-with-Ubuntu-16.04-xenial
I'm now searching your system for contactless devices
** found StickID PN533v2.7 at usb:04cc:2533
I'm not trying serial devices because you haven't told me
-- add the option '--search-tty' to have me looking
-- but beware that this may break existing connections
If you get any errors, please refer to nfcpy installation guide or report an issue directly.

Obtaining the software

The python script will be available for download from your customer account interface if you have placed an order or orders including both of the products below:

1) Any model of our second generation NFC-programmable single-profile TOTP hardware tokens

2) The Stick ID NFC Writer device


The solution will be distributed under Fair Source License. While this means that the source code of the solution will be available for our commercial customers, this not a classic "open-source" license. With Fair Source license, you, as an individual user, can view, download, execute, and modify the code free of charge, but cannot re-distribute it without a prior written approval from Token2

Preparing the environment

The main prerequisite is to have Python installed on your system. Also, before the Token2_Config.py can be used, the python environment on your system has to be configured accordingly. In this article, we will use Ubuntu 20 as an example and configure a virtual Python environment. Configuration of macOS systems should not differ a lot from this, however with Windows, an additional driver installation  may be required.

Follow the steps below to prepare the virtual environment:

1. Create an environment: python3 -m venv venv (or python -m venv venv depending on which executable name the python was configured with)

2. Activate environment: source venv/bin/activate (for Windows, use venv\Scripts\activate.bat)

3. Install requirements: pip install -r requirements.txt


Usage

Run python token2_config.py -h to see the available options. The following example sets a new seed in base32 format and a configuration with the current system time (`--time 0`), a step of 30 seconds (`--step 1`), the HMAC algorithm SHA1 (`--algo 1`) and a display sleep timeout of 30 seconds (`--sleep 2`).

python token2_config.py --seed 48656C6C6F21DEADBEEF48656C6C6F21DEADBEEF --time 0 --step 1 --algo 1 --sleep 2


Note the following:

  • Setting a new configuration will clear the seed of tokens with restricted time sync. Tokens with unrestricted time sync can be configured without clearing the seed.
  •  All configuration parameters must be provided when changing one configuration option.


Full syntax is shown below (also available with -h and --help option):

usage: token2_config.py [-h] [-l LOG] [-s SEED] [--hex HEX] [-t TIME] [-e {1,2}] [-a {1,2}] [-p {1,2,3,4}]

This program can be used to set the seed and the configuration of Token2 TOTP tokens.

optional arguments:

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

  -l LOG, --log LOG     Set logging level. Levels are DEBUG, INFO, WARNING, ERROR, CRITICAL.

seed:

  -s SEED, --seed SEED  Set the seed. In Base32, max. 32 characters.

  --hex true/false             If set, accepts the value of --seed argument to be in hex (does not perform base32 to hex conversion)

configuration:

  -t TIME, --time TIME 

Set the time. UNIX timestamp. Use '0' to set the current device time

  -e {1,2}, --step {1,2}

Set the time step of the OTP. 1=30s, 2=60s

  -a {1,2}, --algo {1,2}

                        Set the OTP algorithm. 1=SHA1, 2=SHA256

  -p {1,2,3,4}, --sleep {1,2,3,4}

                        Set screen sleep timeout. 1=15s, 2=30s, 3=60s, 4=120s

Example 1 (base32 with config arguments): token2_config.py --seed JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP --time 0 --step 1 --algo 1 --sleep 2

Example 2 (seed in hex format):

token2_config.py --seed 48656c6c6f21deadbeef48656c6c6f21deadbeef --hex true

GUI for token2_config.py

The package also includes a GUI created using tkinter module. No more command-line complexities, the GUI allows performing the seed burning and configuration operations using a standard graphical user interface. The GUI allows generating a random seed, scanning the TOTP QR from the current screen and configuring the time step, algorithm and the standby time parameters.



You can launch the GUI script from the same directory by calling:

python3 gui/gui.py


To use the GUI, ensure you have these Python modules installed:
tkinter (usually pre-installed with modern Python3 installations)
PIL (for Windows and macOS)
pyscreenshot (for Linux)
pyzbar