mirror of
https://salsa.debian.org/gnuk-team/gnuk/gnuk.git
synced 2024-09-20 02:40:08 +00:00
e54b7db555
Signed-off-by: NIIBE Yutaka <gniibe@fsij.org>
574 lines
17 KiB
Plaintext
574 lines
17 KiB
Plaintext
Gnuk - An Implementation of USB Cryptographic Token for GnuPG
|
|
|
|
Version 2.1
|
|
2022-0?-??
|
|
Niibe Yutaka
|
|
Free Software Initiative of Japan
|
|
|
|
Release Notes
|
|
=============
|
|
|
|
This is the release of Gnuk, version 2.1, which has major incompatible
|
|
changes to Gnuk 1.
|
|
|
|
Please update your documentation for Gnuk Token, so that the
|
|
instruction of importing keys won't cause any confusion.
|
|
|
|
It has supports of Ed25519 and X25519 (ECDH on Curve25519). It also
|
|
has experimental support of ECDSA on secp256k1 and ECDH on secp256k1.
|
|
|
|
It supports new KDF-DO feature. Please note that this is
|
|
experimental. To use the feature, you need to use newer GnuPG (2.2.6
|
|
or later). You need to prepare the KDF-DO on your token by the
|
|
card-edit/kdf-setup command.
|
|
|
|
With FST-01SZ and GNU/Linux emulation, experimental ack button support
|
|
is available for test.
|
|
|
|
|
|
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).
|
|
|
|
I wish that Gnuk will be a developer's soother who uses GnuPG. I have
|
|
been nervous of storing secret key(s) on usual secondary storage.
|
|
There is a solution with OpenPGP card, but it is not the choice for
|
|
me, as card reader is not common device. With Gnuk, this issue will
|
|
be solved by a USB token.
|
|
|
|
Please look at the graphics of "gnuk.svg" for the software name. My
|
|
son used to be with his NUK(R), always, everywhere. Now, I am with a
|
|
USB Cryptographic Token by "Gnuk", always, everywhere.
|
|
|
|
|
|
FAQ
|
|
===
|
|
|
|
Q0: How Gnuk USB Token is superior than other solutions (OpenPGP
|
|
card 2.0/3.3/3.4, YubiKey, etc.) ?
|
|
https://www.g10code.de/p-card.html
|
|
https://www.yubico.com/
|
|
A0: Good points of Gnuk are:
|
|
* If you have skill of electronics and like DIY, you can build
|
|
Gnuk Token cheaper (see Q8-A8).
|
|
* You can study Gnuk to modify and to enhance. For example, you
|
|
can implement your own authentication method with some sensor
|
|
such as an acceleration sensor.
|
|
* It is "of Free Software"; Gnuk is distributed under GPLv3+,
|
|
"by Free Software"; Gnuk development requires only Free Software
|
|
(GNU Toolchain, Python, etc.),
|
|
"for Free Software"; Gnuk supports GnuPG.
|
|
|
|
Q1: What kind of key algorithm is supported?
|
|
A1: Gnuk version 1.0 only supports RSA-2048.
|
|
Gnuk version 1.2.x supports 255-bit EdDSA, as well as RSA-4096.
|
|
(Note that it takes long time to sign with RSA-4096.)
|
|
|
|
Q2: How long does it take for digital signing?
|
|
A2: It takes a second and a half or so for RSA-2048.
|
|
It takes more than 8 seconds for RSA-4096.
|
|
|
|
Q3: What's your recommendation for target board?
|
|
A3: Orthodox choice is Olimex STM32-H103.
|
|
FST-01SZ (Flying Stone Tiny 01 SZ) is available for sale, and it
|
|
is a kind of the best choice, hopefully. If you have a skill of
|
|
electronics, STM32 Nucleo F103 is the best choice for experiment.
|
|
|
|
Q4: What's version of GnuPG are you using?
|
|
A4: In Debian GNU/Linux system, I use GnuPG modern 2.2.23.
|
|
|
|
Q5: What's version of pcscd and libccid are you using?
|
|
A5: I don't use them, pcscd and libccid are optional, you can use Gnuk
|
|
Token without them.
|
|
I tested pcscd 1.5.5-4 and libccid 1.3.11-2 which were in Debian
|
|
squeeze.
|
|
|
|
Q6: What kinds of hardware is required for development?
|
|
A6: You need a target board plus a JTAG/SWD debugger. If you just
|
|
want to test Gnuk for target boards with DfuSe, JTAG debugger is
|
|
not the requirement. Note that for real use, you need JTAG/SWD
|
|
debugger to enable flash ROM protection.
|
|
|
|
Q7: How much does it cost?
|
|
A7: Olimex STM32-H103 plus ARM-USB-TINY-H cost 70 Euro or so.
|
|
|
|
Q8: How much does it cost for DIY version?
|
|
A8: STM32 Nucleo F103 costs about $10 USD.
|
|
|
|
Q9: I got an error like "gpg: selecting openpgp failed: ec=6.108", what's up?
|
|
A9: Older GnuPG's SCDaemon has problems for handling insertion/removal of
|
|
card/reader. When your newly inserted token is not found by
|
|
GnuPG, try killing scdaemon and let it to be invoked again. I do:
|
|
|
|
$ gpg-connect-agent "SCD KILLSCD" "SCD BYE" /bye
|
|
|
|
and confirm scdaemon doesn't exist, then,
|
|
|
|
$ gpg-connect-agent learn /bye
|
|
|
|
Qa: With GNOME 2, I can't use Gnuk Token for SSH. How can we use it for SSH?
|
|
Aa: You need to deactivate seahorse-agent and gnome-keyring, but use
|
|
gpg-agant for the role of ssh-agent. For gnome-keyring please do:
|
|
|
|
$ gconftool-2 --type bool --set /apps/gnome-keyring/daemon-components/ssh false
|
|
|
|
Qb: With GNOME 3.0, I can't use Gnuk Token at all. Why?
|
|
Ab: That's because gnome-keyring-daemon interferes GnuPG. Type:
|
|
|
|
$ gnome-session-properties
|
|
|
|
and at the tab of "Startup Programs", disable check buttons for
|
|
"GPG Password Agent" and "SSH Key Agent".
|
|
|
|
Qc: With GNOME 3.x (x >= 8?), I can't use Gnuk Token at all. Why?
|
|
Ac: That's because gnome-keyring-daemon interferes GnuPG. Please
|
|
disable the invocation of gnome-keyring-daemon. In Debian
|
|
wheezy, it's in the files /etc/xdg/autostart/gnome-keyring-ssh.desktop
|
|
and /etc/xdg/autostart/gnome-keyring-gpg.desktop.
|
|
We have a line something like:
|
|
|
|
OnlyShowIn=GNOME;Unity;MATE;
|
|
|
|
Please edit this line to:
|
|
|
|
OnlyShowIn=
|
|
|
|
Qd: Do you know a good SWD debugger to connect FST-01 or something?
|
|
Ad: ST-Link/V2 is cheap one. We have a tool/stlinkv2.py as flash ROM
|
|
writer program. STM32 Nucleo F103 comes with the valiant of
|
|
ST-Link/V2. Note that the firmware of ST-Link/V2 is proprietary.
|
|
So, in case of transparency matters, ST-Link/V2 would not be your
|
|
choice.
|
|
I care transparency for our process of manufacturing FST-01SZ (and
|
|
better control by Free Software, in general), thus, I develop
|
|
BBG-SWD, SWD debugger by BeagleBone Green.
|
|
I use ST-Link/V2 for daily development. For serious task like
|
|
flashing product, I use BBG-SWD.
|
|
|
|
|
|
Tested features
|
|
===============
|
|
|
|
Gnuk is tested by test suite. Please see the "tests" directory.
|
|
|
|
* Personalization of the card
|
|
* Changing Login name, URL, Name, Sex, Language, etc.
|
|
* Password handling (PW1, RC, PW3)
|
|
* Key import for three types:
|
|
* key for digital signing
|
|
* key for decryption
|
|
* key for authentication
|
|
* PSO: Digital Signature
|
|
* PSO: Decipher
|
|
* INTERNAL AUTHENTICATE
|
|
* Changing value of password status bytes (0x00C4): forcesig
|
|
* Verify with pin pad
|
|
* Modify with pin pad
|
|
* Card holder certificate (read)
|
|
* Removal of keys
|
|
* Key generation on device side for RSA-2048
|
|
* Overriding key import
|
|
|
|
Original features of Gnuk, tested manually lightly:
|
|
|
|
* OpenPGP card serial number setup
|
|
* Card holder certificate (write by UPDATE BINARY)
|
|
* Upgrading with "EXTERNAL AUTHENTICATE" by reGNUal
|
|
|
|
|
|
Targets
|
|
=======
|
|
|
|
We use Olimex STM32-H103 board and Flying Stone Tiny 01 (FST-01).
|
|
|
|
With DfuSe support, STBee is also our targets. But this target with
|
|
DfuSe is for experiment only, because it is impossible for DfuSe to
|
|
disable read from flash. For real use, please consider killing DfuSe
|
|
and enabling read protection using JTAG debugger.
|
|
|
|
|
|
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.
|
|
|
|
|
|
External source code
|
|
====================
|
|
|
|
Gnuk is distributed with external source code.
|
|
|
|
* chopstx/ -- Chopstx 2.4
|
|
|
|
We use Chopstx as the kernel for Gnuk.
|
|
|
|
Chopstx is distributed under GPLv3+ (with a special exception).
|
|
|
|
|
|
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.
|
|
|
|
|
|
Host Requirements
|
|
=================
|
|
|
|
For GNU/Linux, PC/SC service is an option, you can use GnuPG's
|
|
internal CCID driver instead. If you chose using PC/SC service,
|
|
libccid version >= 1.3.11 is recommended for GNU/Linux.
|
|
|
|
|
|
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
|
|
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.
|
|
--
|