We have been getting many requests from the customers asking to make the NFC Burner tools available under macOS and Linux. The easiest way to achieve this was using cross-platform solutions, and we have chosen to implement this with Python. This allowed us to produce a cross-platform solution that will work on any platform, including Linux, macOS, and Windows. The tool allows burning a seed as well as configuring various options, such as hash type, system clock, and time offset.
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.
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 is not a classic “open-source” license. With a 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 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 JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP — 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.
The 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 TIMESet 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=120sExample 1 (base32 with config arguments):
token2_config.py --seed JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP --time 0 --step 1 --algo 1 --sleep 2Example 2 (seed in hex format):token2_config.py --seed 48656c6c6f21deadbeef48656c6c6f21deadbeef --hex true
