Gnuk - An Implementation of USB Cryptographic Token for GnuPG

						 Version 1.2.15
						     2020-01-24
						   Niibe Yutaka
			      Free Software Initiative of Japan

Release Notes

This is the release of Gnuk, version 1.2.15, which has major incompatible changes to Gnuk 1.0.x. Specifically, it now supports overriding key import, but importing keys (or generating keys) results password reset. Also, you need to import private keys before changing your password. Please update your documentation for Gnuk Token, so that the instruction of importing keys won't cause any confusion.

It has supports of EdDSA, ECDSA (with NIST P256 and secp256k1), and ECDH (with X25519, NIST P256 and secp256k1), but this ECC feature is somehow experimental, and it requires modern GnuPG 2.2 with libgcrypt 1.7.0 or later.

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.

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, 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, 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-01 (Flying Stone Tiny 01) 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.12.

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. However, the firmware of ST-Link/V2 is proprietary. Now, I develop BBG-SWD, SWD debugger by BeagleBone Green.

Tested features

Gnuk is tested by test suite. Please see the test 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.

For experimental PIN-pad support, I connect a consumer IR receive module to FST-01, and use controller for TV. PIN verification is supported by this configuration. Yes, it is not secure at all, since it is very easy to monitor IR output of the controllers. It is just an experiment. Note that hardware needed for this experiment is only a consumer IR receive module which is as cheap as 50 JPY.

Note that you need pinpad support for GnuPG to use PIN-pad enabled Gnuk. The pinpad support for GnuPG is only available in version 2.

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' for your command invocation. I use Python 3.7 and PyUSB 1.0.0.

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 1.18

  We use Chopstx as the kernel for Gnuk.

  Chopstx is distributed under GPLv3+ (with a special exception).

• polarssl/ -- based on PolarSSL 1.2.10 (now mbedTLS)

  Souce code taken from: http://polarssl.org/

  We use PolarSSL for RSA computation, and AES encryption/decryption.

  PolarSSL is distributed under GPLv2+. We use PolarSSL under GPLv3 as our options.

  The file include/polarssl/bn_mul.h is heavily modified for ARM Cortex-M3.

  The function rsa_private in polarssl/library/rsa.c is modified so that it doesn't check T against N. The function rsa_pkcs1_sign is modified to avoid warnings in case of !POLARSSL_PKCS1_V21.

  The functions rsa_pkcs1_verify and rsa_rsassa_pkcs1_v15_verify in include/polarssl/rsa.h and polarssl/library/rsa.c are modified (fixed) for