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.

Hardware requirements

The tool supports two reader backends:

• PC/SC readers (via the pyscard library) — any contactless or contact smart-card reader that your operating system exposes through PC/SC. On Windows this is the built-in Smart Card service; on Linux it is pcscd. This is the recommended option and covers the widest range of readers.
• PN533-based NFC readers (via the nfcpy library) — including our Stick ID NFC Writer device.

By default the tool auto-detects an available reader (trying PC/SC first, then nfcpy). You can force a backend with --transport pcsc or --transport nfcpy, and select a specific PC/SC reader with --reader <name-substring>.

python -m nfc

This is the latest version of nfcpy run in Python 3
I'm now searching your system for contactless devices
** found StickID PN533v2.7 at usb:04cc:2533

Obtaining the software

The source code is available in our public repository under an open-source license. You can clone or download it directly — no purchase is required to use, modify, or redistribute it.

Preparing the environment

The main prerequisite is to have Python installed on your system. Before token2_config.py can be used, the Python environment on your system has to be configured accordingly. In this article, we will use Ubuntu as an example and configure a virtual Python environment. Configuration of macOS systems should not differ much; on Windows, an additional driver installation may be required for some readers.

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

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 the -h / --help option):

usage: token2_config.py [-h] [-l LOG] [--transport {auto,pcsc,nfcpy}] [--reader READER]
                        [-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.

options:
  -h, --help            show this help message and exit
  -l LOG, --log LOG     Set logging level. Levels are DEBUG, INFO, WARNING, ERROR, CRITICAL.
  --transport {auto,pcsc,nfcpy}
                        Reader backend. 'pcsc' = any PC/SC reader, 'nfcpy' = PN533 USB reader.
                        Default: auto (PC/SC first).
  --reader READER       PC/SC reader name substring (when several are connected).

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 the tkinter module. No more command-line complexities — the GUI allows performing the seed burning and configuration operations through a standard graphical user interface. It can generate a random seed, scan the TOTP QR code from the current screen, and configure the time step, algorithm, and standby time parameters.

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

python3 gui.py

To use the GUI, ensure you have these Python modules installed:

tkinter (usually pre-installed with modern Python 3 installations)
PIL / Pillow (for the screen-QR feature on Windows and macOS)
pyscreenshot (for the screen-QR feature on Linux)
pyzbar

The screen-QR feature is optional: without these modules the GUI still runs and burns seeds, and only the "QR from Screen" button is disabled.

Source code

 View on GitHub