From a37f7aca5cf9308626b3ac617bd52ef5439c9400 Mon Sep 17 00:00:00 2001 From: Deon Spengler Date: Sat, 16 Jul 2022 23:52:00 +0200 Subject: [PATCH] Update readme --- README.md | 216 ++++++++---------------------------------------------- 1 file changed, 32 insertions(+), 184 deletions(-) diff --git a/README.md b/README.md index 5229d89..afd6c62 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,5 @@ ***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: +Here is the link to the original project: What's Gnuk? ============ @@ -25,34 +24,46 @@ 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. +How to compile +============== -Source code -=========== +You need GNU toolchain and newlib for 'arm-none-eabi' target. -Gnuk source code is under src/ directory. +On Debian we can install the packages of gcc-arm-none-eabi +and its friends. I'm using: -Note that SHA-2 hash function implementation, src/sha256.c, is based -on the original implementation by Dr. Brian Gladman. See: + 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 - http://brg.a2hosted.com//oldsite/cryptography_technology/sha/index.php -(was at: - http://gladman.plushost.co.uk/oldsite/cryptography_technology/sha/index.php) +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= + +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. -License -======= +Then, type: -It is distributed under GNU General Public Licence version 3 or later -(GPLv3+). Please see src/COPYING. + $ make -Please note that it is distributed with external source code too. -Please read relevant licenses for external source code as well. +Then, we will have "gnuk.elf" under src/build directory. -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. +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. @@ -103,89 +114,9 @@ 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= - -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 ======================== @@ -210,44 +141,6 @@ 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= ../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 ../../.bin - ../../.bin: - Updating card holder certificate - ... - How to run ========== @@ -329,48 +222,3 @@ 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.