193 lines
6.2 KiB
Markdown
193 lines
6.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 USB cryptographic token for GNU Privacy Guard. Gnuk supports OpenPGP card protocol version 3, and it runs on STM32F103 processor (and its compatible). Gnuk allows one to converting a Cheap $2 ST-Link v2 clone into a Hardware GPG Key.
|
|
|
|
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).
|
|
|
|
It also supports RSA-4096, but users should know that it takes more than 8 seconds to sign/decrypt. Key generation of RSA-4096 just fails, because the device doesn't have enough memory.
|
|
|
|
Gnuk supports the Key Derived Function (KDF) functionality. With the KDF function enabled, the PIN is stored as a hash on the Gnuk. To use the feature, you need to use GnuPG (2.2.6 or later). The KDF setting needs to be enabled before any keys is put on the Gnuk. Once a key has been placed on the Gnuk and changes to the KDF settings will be prevented until the Gnuk has been reset. Your Gnuk token can be configured with the card-edit/kdf-setup command of GnuPG.
|
|
|
|
How to build the firmware
|
|
=========================
|
|
|
|
You will need the GNU toolchain and newlib for arm-none-eabi.
|
|
|
|
On Arch Linux this can be installed with the following
|
|
```
|
|
sudo pacman -S arm-none-eabi-gcc arm-none-eabi-newlib
|
|
```
|
|
|
|
On Debian or Ubuntu one can use the following command
|
|
```
|
|
sudo apt-get install gcc-arm-none-eabi
|
|
```
|
|
|
|
Cloning source code and compiling
|
|
---------------------------------
|
|
```
|
|
git clone --recursive https://git.spengler.co.za/deon/gnuk.git gnuk
|
|
cd gnuk/src
|
|
./configure
|
|
make
|
|
```
|
|
|
|
Then, we will have "gnuk.bin" under src/build directory.
|
|
|
|
***Please read section 'USB vendor ID and product ID' below.***
|
|
|
|
How to protect flash ROM
|
|
========================
|
|
|
|
To protect, invoke OpenOCD like (for FST-01):
|
|
|
|
$ openocd -f interface/stlink-v2.cfg -f target/stm32f1x.cfg \
|
|
-c init -c "reset halt" -c "stm32f1x lock 0" -c reset -c exit
|
|
|
|
After power-off / power-on sequence, the contents of flash ROM cannot
|
|
be accessible from JTAG debugger.
|
|
|
|
Unprotecting is:
|
|
|
|
$ openocd -f interface/stlink-v2.cfg -f target/stm32f1x.cfg \
|
|
-c init -c "reset halt" -c "stm32f1x unlock 0" -c reset -c exit
|
|
|
|
Upon unprotection, flash is erased.
|
|
|
|
Note that it would be still possible for some implementation of DfuSe
|
|
to access the contents, even if it's protected. If you really want to
|
|
protect, killing DfuSe and accessing by JTAG debugger is recommended.
|
|
|
|
|
|
Testing Gnuk
|
|
------------
|
|
|
|
Type following command to see Gnuk runs:
|
|
|
|
$ gpg --card-status
|
|
|
|
|
|
Besides, there is a functionality test under tests/ directory. See
|
|
tests/README.
|
|
|
|
|
|
Personalize the Token, import keys, and change the password
|
|
-----------------------------------------------------------
|
|
|
|
You can personalize the token, putting your information like: Name,
|
|
Login name, Sex, Languages, URL. To do so, GnuPG command is:
|
|
|
|
$ gpg --card-edit
|
|
|
|
Note that the factory setting of user password is "123456" and admin
|
|
password is "12345678" as the specification.
|
|
|
|
It is recommended to create your keys on your computer, and import
|
|
them to Gnuk Token. After you create your keys (they must be 2048-bit
|
|
RSA), you can import them.
|
|
|
|
Gnuk supports key generation, but this feature is young and should be
|
|
considered experimental.
|
|
|
|
For detail, please see documentation under doc/. You can see the HTML
|
|
version at: https://www.fsij.org/doc-gnuk/
|
|
|
|
Firmware update
|
|
===============
|
|
|
|
See doc/note/firmware-update.
|
|
|
|
|
|
Debug enabled
|
|
-------------
|
|
|
|
If you compiled with --enable-debug option, Gnuk has two interfaces
|
|
(one is CCID/ICCD device and another is virtual COM port). Open
|
|
virtual COM port by:
|
|
|
|
$ cu -l /dev/ttyACM0
|
|
|
|
and you will see debug output of Gnuk.
|
|
|
|
|
|
|
|
How to debug
|
|
============
|
|
|
|
We can use GDB.
|
|
|
|
$ arm-none-eabi-gdb gnuk.elf
|
|
|
|
|
|
Inside GDB, we can connect OpenOCD by:
|
|
|
|
(gdb) target remote localhost:3333
|
|
|
|
or
|
|
|
|
(gdb) target extended-remote localhost:3333
|
|
|
|
|
|
You can see the output of PCSCD:
|
|
|
|
# /etc/init.d/pcscd stop
|
|
# LIBCCID_ifdLogLevel=7 /usr/sbin/pcscd --debug --foreground
|
|
|
|
|
|
You can observe the traffic of USB using "usbmon". See the file:
|
|
linux/Documentation/usb/usbmon.txt
|
|
|
|
|
|
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.
|
|
|
|
|