Update readme
This commit is contained in:
376
README.md
Normal file
376
README.md
Normal file
@@ -0,0 +1,376 @@
|
||||
***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: <https://alsa.debian.org/gnuk-team/gnuk/gnuk>
|
||||
|
||||
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.
|
||||
|
||||
Build system and Host system
|
||||
============================
|
||||
|
||||
Makefile is written for GNU make. You need Bash 4.x for configure.
|
||||
|
||||
If your bash is not installed as /bin/bash, you need to run configure
|
||||
script prepending 'bash' before './configure'.
|
||||
|
||||
Some tools are written in Python. If your Python is not installed as
|
||||
/usr/bin/python, please prepend 'python' or 'python3' for your command
|
||||
invocation. I use Python 3.8 and PyUSB 1.0.2.
|
||||
|
||||
|
||||
Source code
|
||||
===========
|
||||
|
||||
Gnuk source code is under src/ directory.
|
||||
|
||||
Note that SHA-2 hash function implementation, src/sha256.c, is based
|
||||
on the original implementation by Dr. Brian Gladman. See:
|
||||
|
||||
http://brg.a2hosted.com//oldsite/cryptography_technology/sha/index.php
|
||||
(was at:
|
||||
http://gladman.plushost.co.uk/oldsite/cryptography_technology/sha/index.php)
|
||||
|
||||
|
||||
License
|
||||
=======
|
||||
|
||||
It is distributed under GNU General Public Licence version 3 or later
|
||||
(GPLv3+). Please see src/COPYING.
|
||||
|
||||
Please note that it is distributed with external source code too.
|
||||
Please read relevant licenses for external source code as well.
|
||||
|
||||
The author(s) of Gnuk expect users of Gnuk will be able to access the
|
||||
source code of Gnuk, so that users can study the code and can modify
|
||||
if needed. This doesn't mean person who has a Gnuk Token should be
|
||||
able to access everything on the Token, regardless of its protections.
|
||||
Private keys, and other information should be protected properly.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
How to compile
|
||||
==============
|
||||
|
||||
You need GNU toolchain and newlib for 'arm-none-eabi' target.
|
||||
|
||||
On Debian we can install the packages of gcc-arm-none-eabi
|
||||
and its friends. I'm using:
|
||||
|
||||
binutils-arm-none-eabi 2.37-7+15
|
||||
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
|
||||
GNU Toolchain for 'arm-none-eabi' target.
|
||||
|
||||
Change directory to `src':
|
||||
|
||||
$ cd gnuk-VERSION/src
|
||||
|
||||
Then, run `configure':
|
||||
|
||||
$ ./configure --vidpid=<VID:PID>
|
||||
|
||||
Here, you need to specify USB vendor ID and product ID. For FSIJ's,
|
||||
it's: --vidpid=234b:0000 . Please read section 'USB vendor ID and
|
||||
product ID' above.
|
||||
|
||||
|
||||
Then, type:
|
||||
|
||||
$ make
|
||||
|
||||
Then, we will have "gnuk.elf" under src/build directory.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
How to install
|
||||
==============
|
||||
|
||||
Olimex STM32-H103 board
|
||||
-----------------------
|
||||
|
||||
If you are using Olimex JTAG-Tiny, type following to invoke OpenOCD
|
||||
and write "gnuk.elf" to Flash ROM:
|
||||
|
||||
$ openocd -f interface/ftdi/olimex-jtag-tiny.cfg \
|
||||
-f board/olimex_stm32_h103.cfg \
|
||||
-c "program build/gnuk.elf verify reset exit"
|
||||
|
||||
Command invocation is assumed in src/ directory.
|
||||
|
||||
|
||||
Flying Stone Tiny 01
|
||||
--------------------
|
||||
|
||||
If you are using Flying Stone Tiny 01, you need a SWD writer.
|
||||
|
||||
OpenOCD 0.9.0 now supports ST-Link/V2. We can use it like:
|
||||
|
||||
$ openocd -f interface/stlink-v2.cfg -f target/stm32f1x.cfg \
|
||||
-c "program build/gnuk.elf verify reset exit"
|
||||
|
||||
|
||||
STBee
|
||||
-----
|
||||
|
||||
Note that this is only for your experiment; Your private key materials
|
||||
on the board can be accessed by DfuSe.
|
||||
|
||||
Reset the board with "USER" switch pushed. Type following to write
|
||||
to flash:
|
||||
|
||||
# cd ../tool
|
||||
# ./dfuse.py ../src/build/gnuk.hex
|
||||
|
||||
Then, reset the board.
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
(Optional) Configure serial number and X.509 certificate
|
||||
========================================================
|
||||
|
||||
This is completely optional.
|
||||
|
||||
For this procedure, you need python and pyscard (python-pyscard
|
||||
package in Debian) or PyUSB (python-usb package in Debian).
|
||||
|
||||
(1) [pyscard] Stop scdaemon
|
||||
[PyUSB] Stop the pcsc daemon.
|
||||
|
||||
If scdaemon is running, please kill it, or you will get "Smartcard
|
||||
Exception" by "Sharing violation".
|
||||
|
||||
$ gpg-connect-agent "SCD KILLSCD" "SCD BYE" /bye
|
||||
|
||||
In case of PyUSB tool, you need to stop pcscd.
|
||||
|
||||
# systemctl stop pcscd
|
||||
|
||||
|
||||
(2) [Optional] Write fixed serial number
|
||||
|
||||
If you use fixed serial number in the file 'GNUK_SERIAL_NUMBER', you can do:
|
||||
|
||||
$ EMAIL=<YOUR-EMAIL-ADDRESS> ../tool/gnuk_put_binary_usb.py -s ../GNUK_SERIAL_NUMBER
|
||||
Writing serial number
|
||||
...
|
||||
|
||||
(3) [Optional] Write card holder certificate
|
||||
|
||||
If you have card holder certificate binary file, you can do:
|
||||
|
||||
$ ../tool/gnuk_put_binary_usb.py ../../<YOUR-CERTIFICATE>.bin
|
||||
../../<YOUR-CERTIFICATE>.bin: <LENGTH-OF-YOUR-CERTIFICATE>
|
||||
Updating card holder certificate
|
||||
...
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
Git Repositories
|
||||
================
|
||||
|
||||
Please use: https://salsa.debian.org/gnuk-team/gnuk/
|
||||
|
||||
You can get it by:
|
||||
|
||||
$ git clone https://salsa.debian.org/gnuk-team/gnuk/gnuk.git
|
||||
|
||||
It's also available at: www.gniibe.org
|
||||
You can browse at: https://git.gniibe.org/cgit/gnuk/gnuk.git/
|
||||
|
||||
I put Chopstx as a submodule of Git. Please do this:
|
||||
|
||||
$ git submodule update --init
|
||||
|
||||
|
||||
Information on the Web
|
||||
======================
|
||||
|
||||
For more information, please visit: https://www.fsij.org/gnuk/
|
||||
|
||||
Please see the FST-01 support pages:
|
||||
|
||||
https://www.gniibe.org/category/fst-01.html
|
||||
|
||||
Please consider to join Gnuk-users mailing list:
|
||||
|
||||
https://lists.gnupg.org/mailman/listinfo/gnuk-users
|
||||
|
||||
|
||||
|
||||
Your Contributions
|
||||
==================
|
||||
|
||||
FSIJ welcomes your contributions. Please assign your copyright
|
||||
to FSIJ (if possible), as I do.
|
||||
|
||||
|
||||
Foot note
|
||||
==========
|
||||
|
||||
* NUK(R) is a registered trademark owend by MAPA GmbH, Germany.
|
||||
Reference in New Issue
Block a user