-Gnuk - software for GPG USB Token
+Gnuk - An Implementation of USB Cryptographic Token for GnuPG
- Version 0.4
- 2010-11-09
- Niibe Yutaka
+ Version 1.1.5
+ 2015-06-03
+ Niibe Yutaka
Free Software Initiative of Japan
+Warning
+=======
+
+This is another experimental release of Gnuk, version 1.1.5, which has
+incompatible changes to Gnuk 1.0.x. Specifically, it now supports
+overriding key import, but importing keys (or generating keys) results
+password reset. Please update your documentation for Gnuk Token, so
+that the instruction of importing keys won't cause any confusion. It
+has supports of ECDSA (with NIST P256 and secp256k1) and EdDSA with
+EdDSA, but this feature is pretty much experimental, and it requires
+development version of GnuPG with newest version of libgcrypt. You
+will not able to keep using EdDSA keys, as the key format is subject
+to change. It also support RSA-4096 experimentally, but users should
+know that it takes more than 8 second to sign/decrypt.
+
+
What's Gnuk?
============
-Gnuk is software implementation of a USB token for GNU Privacy Guard.
-Gnuk supports OpenPGP card protocol version 2, and it runs on STM32
-processor.
+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.
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.
-While I want to work at different places, but it is not the choice for
-me to bring a card reader all the time. With Gnuk, this issue will be
-solved by a USB token which is small enough.
+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. I will be with a
-USB Token by Gnuk everywhere.
+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, GPF Crypto Stick, etc.) ?
+ http://www.g10code.de/p-card.html
+ http://www.privacyfoundation.de/crypto_stick/
+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.
+ Development version of Gnuk (1.1.x) supports 256-bit ECDSA and EdDSA,
+ as well as RSA 4096-bit. But 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.
+
+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.
+
+Q4: What's version of GnuPG are you using?
+A4: In Debian GNU/Linux system, I use gnupg 1.4.12-7 and gnupg-agent
+ 2.0.20-1.
+
+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
+ 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.
+
+Q9: I got an error like "gpg: selecting openpgp failed: ec=6.108", what's up?
+A9: 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: Do you know a good SWD debugger to connect FST-01 or something?
+Ac: ST-Link/V2 is cheap one. We have a tool/stlinkv2.py as flash ROM
+ writer program.
+
+Qd: With GNOME 3.x (x >= 8?), I can't use Gnuk Token at all. Why?
+Ad: Please set the configration variable OnlyShowIn as none. Like:
+
+ OnlyShowIn=
+
+ In the files of /etc/xdg/autostart/gnome-keyring-gpg.desktop and
+ /etc/xdg/autostart/gnome-keyring-ssh.desktop
+
+
Release notes
=============
-This is fifth release of Gnuk. While it works well for specific
-usages, it is still experimental.
+This is third experimental release in version 1.1 series of Gnuk.
+
+While it is daily use by its developer, some newly introduced features
+(including ECDSA/EdDSA, key generation and firmware upgrade) should be
+considered experimental. ECDSA/EdDSA is really experimental.
+Further, EdDSA is much experimental. You won't be able to keep using
+the EdDSA key, as the key format of GnuPG is subject to change.
Tested features are:
* 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
+ * Overriding key import
-It is known not-working well:
+Original features of Gnuk, tested lightly:
- * Key import multiple times
+ * OpenPGP card serial number setup
+ * Card holder certificate (write by UPDATE BINARY)
+ * Upgrading with "EXTERNAL AUTHENTICATE" by reGNUal
- * Changing value of password status bytes (0x00C4).
-
- * For some version of kernel and libccid, --enable-debug can't
- work well. Please disable DEBUG option if it doesn't work well.
-
-Not (yet) supported feature(s):
+It is known not-working well:
- * card holder certificate (its size matters (> 1KiB?), if we support)
+ * It is known that the combination of libccid 1.4.1 (or newer)
+ with libusb 1.0.8 (or older) has a minor problem. It is
+ rare but it is possible for USB communication to be failed,
+ because of a bug in libusb implementation. Use libusbx
+ 1.0.9 or newer, or don't use PC/SC, but use internal CCID
+ driver of GnuPG.
Targets
=======
-We use Olimex STM32-H103 board. DFU support is added, it's mainly for
-CQ STARM and STBee Mini but those targets are not tested extensively.
-That's because we don't have a Free Software tool to write through
-DFU.
+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.
-I think that it could run on Olimex STM32-P103, or STBee too.
-Besides, we are porting it to STM32 Primer 2.
+For 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.
Souce 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://gladman.plushost.co.uk/oldsite/cryptography_technology/sha/index.php
+
License
=======
(GPLv3+). Please see src/COPYING.
Please note that it is distributed with external source code too.
-Please read relevant licenses for 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. This doesn't mean person who has a USB Token by
-Gnuk should be able to acess everything on the Token, regardless of
-its protections. Private keys, random bytes, and other information
-should be protected properly.
+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.
-* ChibiOS_2.0.2/ -- ChibiOS/RT 2.0.2
+* chopstx/ -- Chopstx 0.04
- Taken from http://chibios.sourceforge.net/
- Note that CRLF is converted to LF in this repository.
- We use ChibiOS/RT as the kernel for Gnuk.
+ We use Chopstx as the kernel for Gnuk.
-* polarssl-0.14.0/ -- PolarSSL 0.14.0
+ Chopstx is distributed under GPLv3+ (with a special exception).
- Taken from http://polarssl.org/
- We use PolarSSL for RSA computation, AES encryption/decryption
- and SHA-1 computation.
-* STM32_USB-FS-Device_Driver/ -- a part of USB-FS-Device_Lib
-* Virtual_COM_Port/ -- a part of USB-FS-Device_Lib
+* polarssl/ -- PolarSSL 1.2.10
- STM32F10x USB Full Speed Device Library (USB-FS-Device_Lib)
- is a STM32F10x library for USB functionality.
+ Souce code taken from: http://polarssl.org/
- I took Libraries/STM32_USB-FS-Device_Driver and
- Project/Virtual_COM_Port in STM32_USB-FS-Device_Lib distribution.
- See http://www.st.com for detail.
+ We use PolarSSL for RSA computation, and AES encryption/decryption.
+ PolarSSL is distributed under GPLv2+. We use PolarSSL under GPLv3
+ as our options.
-Host Requirements
-=================
+ 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 last argument SIG, as the memory at SIG aren't modified
+ by those routines.
+
+ The constant POLARSSL_MPI_MAX_SIZE in include/polarssl/bignum.h is
+ modified for 2048-bit keys only Gnuk.
-For GNU/Linux, libccid version >= 1.3.11 is required.
-libccid version == 1.3.9 is known not working well by the issue [r4235].
+ The function mpi_mul_hlp in library/bignum.c is modified for more
+ optimization for ARM Cortex-M3. Functions mpi_montred, mpi_sub_hlp,
+ mpi_sub_abs, mpi_mul_mpi, mpi_montmul, and mpi_exp_mod are modified
+ to avoid side channel attacks. Note that we don't use RSA-blinding
+ technique for Gnuk. Function mpi_gen_prime and mpi_is_prime are
+ modified to use Fouque-Tibouchi method. Function mpi_exp_mod is
+ modified to use new function mpi_montsqr for speed up.
-I think that it should not be requirment but the kernel version of my use is:
-Linux version 2.6.32-5-686 (Debian 2.6.32-18) (ben@decadent.org.uk) (gcc version 4.3.5 (Debian 4.3.5-2) ) #1 SMP Sat Jul 24 02:27:10 UTC 2010
+ The file library/aes.c is modified so that some constants can
+ go to .sys section.
-Linux 2.6.30 is known *NOT* working well with DEBUG option.
-Linux 2.6.24 is known working well with DEBUG option.
+ The file include/polarssl/config.h are modified not to define
+ POLARSSL_HAVE_LONGLONG to avoid linking libgcc, to define
+ POLARSSL_AES_ROM_TABLES to have AES tables, not to define
+ POLARSSL_CIPHER_MODE_CTR, POLARSSL_FS_IO, POLARSSL_PKCS1_V21,
+ POLARSSL_SELF_TEST, and POLARSSL_PADLOCK_C, and only define
+ POLARSSL_GENPRIME when defined KEYGEN_SUPPORT.
+
+
+USB vendor ID and product ID (USB device ID)
+============================================
+
+When you have a vender 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.
-See http://github.com/esden/summon-arm-toolchain/ for preparation of
-GNU Toolchain for 'arm-none-eabi' target.
+There is "gcc-arm-embedded" project. See:
+
+ https://launchpad.net/gcc-arm-embedded/
+
Change directory to `src':
Then, run `configure':
- $ ./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.
Type:
$ make
-In the make process, it takes time for the command of
-
- dd if=/dev/random bs=1 of=random_bits count=1024
+Then, we will have "gnuk.elf" under src/build directory.
-Don't just wait, but do some other work on your PC.
-/dev/random needs entropy to finish.
-Then, we will have "gnuk.elf".
-
-
-How to run
-==========
+How to install
+==============
Olimex STM32-H103 board
-----------------------
If you are using Olimex JTAG-Tiny, type following to invoke OpenOCD:
- $ openocd -f interface/olimex-jtag-tiny.cfg -f board/olimex_stm32_h103.cfg
+ $ openocd -f interface/ftdi/olimex-jtag-tiny.cfg -f board/olimex_stm32_h103.cfg
Then, with another terminal, type following to write "gnuk.elf" to Flash ROM:
$
-CQ STARM
---------
+Flying Stone Tiny 01
+--------------------
-Put jumper for J6 to enable DfuSe. Connecting the board, and type:
+If you are using Flying Stone Tiny 01, you need a SWD writer.
- # cd ../tool
- # ./dfuse.py ../src/gnuk.hex
+OpenOCD 0.6.1 now supports ST-Link/V2. We can use it:
-Then, remove the jumper and reset the board.
+ $ openocd -f interface/stlink-v2.cfg -f target/stm32f1x_stlink.cfg
+But it doesn't support option bytes handling (protection) yet.
-STBee Mini
-----------
+
+STBee
+-----
Reset the board with "USER" switch pushed. Type following to write
to flash:
# cd ../tool
- # ./dfuse.py ../src/gnuk.hex
+ # ./dfuse.py ../src/build/gnuk.hex
Then, reset the board.
+How to protect flash ROM
+========================
+
+Invoke your OpenOCD and type:
+
+ $ telnet localhost 4444
+ > reset halt
+ > stm32f1x lock 0
+ > reset
+ > shutdown
+
+After power-off / power-on sequence, the contents of flash ROM cannot
+be accessible from JTAG debugger.
+
+Note that it would be still possible for some implementation of DfuSe
+to access the contents. If you want to protect, killing DfuSe and
+accessing by JTAG debugger is recommended.
+
+
+How to configure
+================
+
+You need python and pyscard (python-pyscard package in Debian) or
+PyUSB 0.4.3 (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.
+
+ # /etc/init.d/pcscd stop
+
+
+(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.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.py ../../<YOUR-CERTIFICATE>.bin
+ ../../<YOUR-CERTIFICATE>.bin: <LENGTH-OF-YOUR-CERTIFICATE>
+ Updating card holder certificate
+ ...
+
+
+How to run
+==========
+
Debug enabled
-------------
and you will see debug output of Gnuk.
-Libccid fix needed
-------------------
+Testing Gnuk
+------------
-For libccid, we need following change:
+Type following command to see Gnuk runs:
---- /etc/libccid_Info.plist.dpkg-dist 2009-07-29 06:50:20.000000000 +0900
-+++ /etc/libccid_Info.plist 2010-09-05 09:09:49.000000000 +0900
-@@ -104,6 +104,7 @@
-
- <key>ifdVendorID</key>
- <array>
-+ <string>0x234B</string>
- <string>0x08E6</string>
- <string>0x08E6</string>
- <string>0x08E6</string>
-@@ -237,6 +238,7 @@
-
- <key>ifdProductID</key>
- <array>
-+ <string>0x0000</string>
- <string>0x2202</string>
- <string>0x3437</string>
- <string>0x3438</string>
-@@ -370,6 +372,7 @@
-
- <key>ifdFriendlyName</key>
- <array>
-+ <string>FSIJ USB Token</string>
- <string>Gemplus Gem e-Seal Pro</string>
- <string>Gemplus GemPC Twin</string>
- <string>Gemplus GemPC Key</string>
-------------------
+ $ gpg --card-status
-Testing Gnuk
-------------
+Besides, there is a functionality test under test/ directory. See
+test/README.
-Try following to see Gnuk runs:
- $ gpg --card-status
+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
-For more, see doc/DEMO.
+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: http://www.fsij.org/doc-gnuk/
How to debug
linux/Documentation/usb/usbmon.txt
-Read-only Git Repository
-========================
+Firmware update
+===============
+
+See doc/note/firmware-update.
+
+
+Git Repositories
+================
+
+Please use: https://anonscm.debian.org/cgit/gnuk/gnuk/
You can get it by:
+
+ $ git clone git://anonscm.debian.org/gnuk/gnuk/gnuk.git
+
+It's also available at: www.gniibe.org
+You can browse at: http://git.gniibe.org/gitweb?p=gnuk/gnuk.git;a=summary
- $ git clone http://www.gniibe.org/git/gnuk.git/
+I put Chopstx as a submodule of Git. Please do this:
+
+ $ git submodule init
+ $ git submodule update
+
+We have migrated from ChibiOS/RT to Chopstx. If you have old code of
+ChibiOS/RT, you need:
+
+ Edit .git/config to remove chibios reference
+ git rm --cached chibios
Information on the Web
======================
-Please see: http://www.fsij.org/gnuk/
+Please visit: http://www.fsij.org/gnuk/
+
+Please see the FST-01 support pages:
+
+ http://www.gniibe.org/category/fst-01.html
+
+Please consider to join Gnuk-users mailing list:
+
+ https://lists.alioth.debian.org/mailman/listinfo/gnuk-users
Your Contributions
Foot note
==========
+
* NUK(R) is a registered trademark owend by MAPA GmbH, Germany.
--
projects / gnuk / gnuk.git / blobdiff