Update readme
This commit is contained in:
252
README.md
252
README.md
@@ -1,4 +1,5 @@
|
|||||||
***Note:*** *This fork of Gnuk fixes some compiling bugs and focuses on using the ST-Link v2 clone hardware.*
|
***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/>
|
Here is the link to the original project: <http://git.gniibe.org/cgit/gnuk/gnuk.git/>
|
||||||
|
|
||||||
What's Gnuk?
|
What's Gnuk?
|
||||||
@@ -12,59 +13,134 @@ It also supports RSA-4096, but users should know that it takes more than 8 secon
|
|||||||
|
|
||||||
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.
|
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.
|
||||||
|
|
||||||
Build system and Host system
|
How to build the firmware
|
||||||
============================
|
=========================
|
||||||
|
|
||||||
Makefile is written for GNU make. You need Bash 4.x for configure.
|
You will need the GNU toolchain and newlib for arm-none-eabi.
|
||||||
|
|
||||||
If your bash is not installed as /bin/bash, you need to run configure
|
On Arch Linux this can be installed with the following
|
||||||
script prepending 'bash' before './configure'.
|
```
|
||||||
|
sudo pacman -S arm-none-eabi-gcc arm-none-eabi-newlib
|
||||||
|
```
|
||||||
|
|
||||||
Some tools are written in Python. If your Python is not installed as
|
On Debian or Ubuntu one can use the following command
|
||||||
/usr/bin/python, please prepend 'python' or 'python3' for your command
|
```
|
||||||
invocation. I use Python 3.8 and PyUSB 1.0.2.
|
sudo apt-get install gcc-arm-none-eabi
|
||||||
|
```
|
||||||
|
|
||||||
How to compile
|
Cloning source code and compiling
|
||||||
==============
|
---------------------------------
|
||||||
|
```
|
||||||
|
git clone --recursive https://git.spengler.co.za/deon/gnuk.git gnuk
|
||||||
|
cd gnuk/src
|
||||||
|
./configure
|
||||||
|
make
|
||||||
|
```
|
||||||
|
|
||||||
You need GNU toolchain and newlib for 'arm-none-eabi' target.
|
Then, we will have "gnuk.bin" under src/build directory.
|
||||||
|
|
||||||
On Debian we can install the packages of gcc-arm-none-eabi
|
***Please read section 'USB vendor ID and product ID' below.***
|
||||||
and its friends. I'm using:
|
|
||||||
|
|
||||||
binutils-arm-none-eabi 2.37-7+15
|
How to protect flash ROM
|
||||||
gcc-arm-none-eabi 15:10.3-2021.07-4
|
========================
|
||||||
libnewlib-arm-none-eabi 3.3.0-1.3
|
|
||||||
gdb-multiarch 10.1-2
|
|
||||||
|
|
||||||
Or else, see https://launchpad.net/gcc-arm-embedded for preparation of
|
To protect, invoke OpenOCD like (for FST-01):
|
||||||
GNU Toolchain for 'arm-none-eabi' target.
|
|
||||||
|
|
||||||
Change directory to `src':
|
$ openocd -f interface/stlink-v2.cfg -f target/stm32f1x.cfg \
|
||||||
|
-c init -c "reset halt" -c "stm32f1x lock 0" -c reset -c exit
|
||||||
|
|
||||||
$ cd gnuk-VERSION/src
|
After power-off / power-on sequence, the contents of flash ROM cannot
|
||||||
|
be accessible from JTAG debugger.
|
||||||
|
|
||||||
Then, run `configure':
|
Unprotecting is:
|
||||||
|
|
||||||
$ ./configure --vidpid=<VID:PID>
|
$ openocd -f interface/stlink-v2.cfg -f target/stm32f1x.cfg \
|
||||||
|
-c init -c "reset halt" -c "stm32f1x unlock 0" -c reset -c exit
|
||||||
|
|
||||||
Here, you need to specify USB vendor ID and product ID. For FSIJ's,
|
Upon unprotection, flash is erased.
|
||||||
it's: --vidpid=234b:0000 . Please read section 'USB vendor ID and
|
|
||||||
product ID' above.
|
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.
|
||||||
|
|
||||||
|
|
||||||
Then, type:
|
Testing Gnuk
|
||||||
|
------------
|
||||||
|
|
||||||
$ make
|
Type following command to see Gnuk runs:
|
||||||
|
|
||||||
Then, we will have "gnuk.elf" under src/build directory.
|
$ gpg --card-status
|
||||||
|
|
||||||
If you are not the authorized vendor, please never distribute this
|
|
||||||
file of "gnuk.elf", which includes VID:PID in the image. If you would
|
|
||||||
like to distribute the image (for example, to check if it's
|
|
||||||
reproducible or not), the file "gnuk-no-vidpid.elf" is the one with no
|
|
||||||
VID:PID.
|
|
||||||
|
|
||||||
|
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)
|
USB vendor ID and product ID (USB device ID)
|
||||||
@@ -114,111 +190,3 @@ your own USB vendor ID and product ID. Please replace vendor string
|
|||||||
and possibly product string to yours, when you modify Gnuk.
|
and possibly product string to yours, when you modify Gnuk.
|
||||||
|
|
||||||
|
|
||||||
How to install
|
|
||||||
==============
|
|
||||||
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
How to run
|
|
||||||
==========
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
|
|
||||||
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/
|
|
||||||
|
|
||||||
|
|
||||||
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
|
|
||||||
|
|
||||||
|
|
||||||
Firmware update
|
|
||||||
===============
|
|
||||||
|
|
||||||
See doc/note/firmware-update.
|
|
||||||
|
|||||||
Reference in New Issue
Block a user