122 lines
5.2 KiB
Markdown
122 lines
5.2 KiB
Markdown
***Note:*** *This fork of Gnuk fixes some compiling bugs and focuses on using the "ST-Link V2" clone hardware.*
|
|
|
|
Here is the link to the original project: <http://git.gniibe.org/cgit/gnuk/gnuk.git/>
|
|
|
|
What's Gnuk?
|
|
============
|
|
Gnuk is an implementation of a USB cryptographic security token that supports the OpenPGP card protocol version 2. It runs on a STM32F103 processor (and its compatible). In short it allows one to convert a cheap $2 "ST-Link V2" clone device into a hardware security token.
|
|
|
|
It has supports of Ed25519 and X25519 (ECDH on Curve25519). It also has experimental support of ECDSA (on NIST P256 and secp256k1) and ECDH (on NIST P256 and secp256k1).
|
|
|
|
Gnuk supports the Key Derived Function (KDF) functionality. To use this feature one will need to use GnuPG 2.2.6 or later.
|
|
|
|
How to build the Gnuk firmware
|
|
==============================
|
|
You will need the GNU toolchain for arm-none-eabi and newlib.
|
|
|
|
To clone the source code and compile, use the following commands.
|
|
```
|
|
git clone --recursive https://git.spengler.co.za/deon/gnuk.git gnuk
|
|
cd gnuk/src
|
|
./configure --vidpid=1337:0010
|
|
make
|
|
```
|
|
|
|
Then, you will have "gnuk.bin" under src/build directory.
|
|
|
|
***Please read section 'USB vendor ID and product ID' below.***
|
|
|
|
How to flash the Gnuk firmware
|
|
==============================
|
|
In order to flash the firmware ensure that you have openocd installed.
|
|
|
|
Execute openocd and connect with telnet
|
|
```
|
|
openocd -f ../misc/stm32f103.cfg
|
|
telnet localhost 4444
|
|
```
|
|
|
|
Use the following commands to unlock, flash the firmware and lock the device again.
|
|
```
|
|
reset halt
|
|
stm32f1x unlock 0
|
|
reset halt
|
|
flash write_bank 0 ./build/gnuk.bin 0
|
|
stm32f1x lock 0
|
|
reset halt
|
|
```
|
|
|
|
Testing Gnuk
|
|
============
|
|
Type following command to see if GnuPG detects the Gnuk token.
|
|
```
|
|
gpg --card-status
|
|
```
|
|
|
|
***See tests/README for functionality tests.***
|
|
|
|
Personalize the Token, import keys, and change the password
|
|
===========================================================
|
|
You can personalize your token by putting in your information like: Name, Login and Language.
|
|
|
|
The KDF setting needs to be enabled before any keys are imported into the Gnuk token. Once a key has been imported the KDF setting can't be changed until the token has been reset.
|
|
|
|
***Note:*** That the factory user password is "123456" and admin password is "12345678". It is recommended to create your keys on your computer, and import them into the token. Gnuk supports key generation, but this feature is young and should be considered experimental.
|
|
|
|
To configure your Gnuk token use the following command.
|
|
```
|
|
gpg --card-edit
|
|
```
|
|
|
|
For further details, please see documentation under doc.
|
|
|
|
Firmware update
|
|
===============
|
|
See doc/note/firmware-update.
|
|
|
|
How to debug
|
|
============
|
|
Ensure that you have arm-none-eabi-gdb installed and then you must configure and compile the Gnuk firmware with --enable-debug option. After flashing Gnuk debug firmware one will see two interfaces, one is CCID/ICCD device and the another is a virtual COM port.
|
|
|
|
Open the virtual COM with the following command:
|
|
```
|
|
picocom /dev/ttyACM0
|
|
```
|
|
and you will see debug output of Gnuk firmware.
|
|
|
|
You can now use GDB with the following command.
|
|
```
|
|
arm-none-eabi-gdb src/build/gnuk.elf
|
|
```
|
|
|
|
Inside GDB, we can connect OpenOCD by:
|
|
```
|
|
(gdb) target remote localhost:3333
|
|
```
|
|
|
|
You can see the output of PCSCD with the following command:
|
|
```
|
|
/usr/bin/pcscd --debug --foreground
|
|
```
|
|
|
|
You can also observe the traffic of the USB interface using "usbmon".
|
|
|
|
USB vendor ID and product ID (USB device ID)
|
|
============================================
|
|
When you have a vendor ID and assign a product ID for Gnuk, edit the file GNUK_USB_DEVICE_ID and add an entry for yours. In this case, please contact Niibe, so that it is listed to the file in the official release of the source code.
|
|
|
|
When you are modifing Gnuk and installing the binary to device, you should replace the vendor string and serial number to yours (in the file GNUK_USB_DEVICE_ID and SERIALNO of the script of src/configure), so that users can see it's not by original vendor, and it is modified version.
|
|
|
|
FSIJ allows you to use USB device ID of FSIJ (234b:0000) for devices with Gnuk under one of following conditions:
|
|
* For everyone for experimental purpose:
|
|
- You must not distribute a binary with FSIJ's USB device ID, but must use the binary by yourself only for your experiment. Note that "Distributing binary" includes distributing a device which holds the binary.
|
|
* For general individuals:
|
|
- You must use your Gnuk device with a card serial number which is *not* by FSIJ. Easy one would be a card serial number generated by chip unique ID.
|
|
* For individuals with explicit permission from FSIJ.
|
|
- You should have an assigned card serial number by FSIJ, please use that number for your device.
|
|
(There a file 'GNUK_SERIAL_NUMBER' in the official release.)
|
|
|
|
FSIJ could give companies or business entities "second source manufacturer" license to use USB device ID of FSIJ for devices with unmodified version of Gnuk, provided they support Free Software and respect users' freedom for computing. Please ask FSIJ for the license.
|
|
|
|
Otherwise, companies which want to distribute Gnuk devices, please use your own USB vendor ID and product ID. Please replace vendor string and possibly product string to yours, when you modify Gnuk.
|