Gnuk - software for GnuPG USB Token Version 0.14 2011-10-07 Niibe Yutaka Free Software Initiative of Japan 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. 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. Please look at the graphics of "gnuk.svg" for the software name. My son used to be with his NUK(R), always, everywhere. I am with a USB 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: IMRHO, not quite. There is no ready-to-use out-of-box product. (It is welcome for me that some vendor will manufacture Gnuk USB Token. Even I can help design of hardware, if needed.) Good points 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 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 only supports 2048-bit RSA. 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. If you have skill of electronics and like DIY, STM32 part of STM8S Discovery Kit might be the best choice. Currently FST-01 (Flying Stone Tiny 01) is under development, it will be the best choice, hopefully. Q4: What's version of GnuPG are you using? A4: In Debian GNU/Linux system, I use gnupg 1.4.11-3 and gnupg-agent 2.0.14-2 (in sid). With older versions, you can only sign with SHA1. See: http://www.fsij.org/gnuk/gnupg2-fixes-needed Q5: What's version of pcscd and libccid are you using? A5: In Debian GNU/Linux system, I use pcscd 1.5.5-4 and libccid 1.3.11-2, which is in squeeze. Note that you need to edit /etc/libccid_Info.plist when using libccid (< 1.4.1). Q6: What kinds of hardware is required for development? A6: You need a target board plus a JTAG 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 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: STM8S Discovery Kit costs 750 JPY (< $10 USD) only. You can build your own JTAG debugger using FTDI2232 module (1450 JPY), see: http://www.fsij.org/gnuk/jtag_dongle_ftdi2232 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 (problems are fixed in trunk). When your newly inserted token is not found by GnuPG, try killing scdaemon and let it to be invoked again. I do: $ killall -9 scdaemon and confirm scdaemon doesn't exist, then, $ gpg-connect-agent learn /bye Release notes ============= This is fifteenth release of Gnuk. While it works well for specific usages and it is considered stable, it is still somewhat experimental. 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 It is known not-working well: * For some version of kernel and libccid, --enable-debug can't work well. Please disable DEBUG option if it doesn't work well. * Card holder certificate It is implemented in Gnuk side. But its size matters (> 1KB). GnuPG cannot handle a data object of large size with PC/SC backend. Specifically, handle_transmit function in pcsc-wrapper.c uses the buffer of size 1024-byte. Not supported feature(s): * Overriding key import. You need to remove all keys first. * Key generation on device side Targets ======= We use Olimex STM32-H103 board. We also use STM32 part of STM8S Discovery Kit. With DfuSe support, CQ STARM, STBee, and STBee Mini are also our targets. But those targets with DfuSe are basically not for normal use but for experiments, because it would be impossible for DfuSe to disable read from flash. For real use, please consider killing DfuSe and enable read protection using JTAG debugger. I think that it could run on Olimex STM32-P103, or other boards with STM32F103. Besides, we are porting it to STM32 Primer 2. For PIN-pad support, I connect a consumer IR receive module to STBee Mini and STM8S Discovery Kit, 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. Another PIN-pad support is connecting rotary encoder, push switch and 7-segment LED display. Both of PIN verification and PIN modification are supported for this circuit extension. Souce code ========== Gnuk source code is under src/ directory. 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, too. 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 USB Token by Gnuk should be able to acess 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.8/ -- ChibiOS/RT 2.0.8 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. * polarssl-0.14.0/ -- PolarSSL 0.14.0 Taken from http://polarssl.org/ We use PolarSSL for RSA computation, AES encryption/decryption and SHA-1 computation. The file include/polarssl/bn_mul.h is heavily modified for ARM Cortex-M3. * STM32_USB-FS-Device_Driver/ -- a part of USB-FS-Device_Lib * Virtual_COM_Port/ -- a part of USB-FS-Device_Lib STM32F10x USB Full Speed Device Library (USB-FS-Device_Lib) is a STM32F10x library for USB functionality. 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. Host Requirements ================= For GNU/Linux, libccid version >= 1.3.11 is required. libccid version == 1.3.9 is known not working well by the issue [r4235]. 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 Linux 2.6.30 is known *NOT* working well with DEBUG option. Linux 2.6.24 is known working well with DEBUG option. How to compile ============== You need GNU toolchain and newlib for 'arm-none-eabi' target. See http://github.com/uwehermann/summon-arm-toolchain/ for preparation of GNU Toolchain for 'arm-none-eabi' target. Change directory to `src': $ cd gnuk-VERSION/src Then, run `configure': $ ./configure Type: $ make Then, we will have "gnuk.elf". 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 Then, with another terminal, type following to write "gnuk.elf" to Flash ROM: $ telnet localhost 4444 > reset halt > flash write_image erase gnuk.elf > reset > exit $ STM8S Discovery Kit ------------------- If you are using FTDI-2232D module and the connection is standard, type: $ openocd -f interface/openocd-usb.cfg -f target/stm32.cfg Initially, the flash ROM of the chip is protected. you need to do: $ telnet localhost 4444 > reset halt > stm32x unlock 0 > reset > shutdown $ and re-connect the board. Note that power-off / power-on sequence is required to reset flash ROM. Then, invoke OpenOCD again and telnet to connect OpenCD and write image as above example of Olimex STM32-H103. CQ STARM -------- Put jumper for J6 to enable DfuSe. Connecting the board, and type: # cd ../tool # ./dfuse.py ../src/gnuk.hex Then, remove the jumper and reset the board. STBee and STBee Mini -------------------- Reset the board with "USER" switch pushed. Type following to write to flash: # cd ../tool # ./dfuse.py ../src/gnuk.hex Then, reset the board. How to protect flash ROM ======================== Invoke your OpenOCD and type: $ telnet localhost 4444 > reset halt > stm32x 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 (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". $ killall -9 scdaemon 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= ../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 ../../.bin ../../.bin: 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. Libccid fix needed ------------------ For libccid (< 1.4.1), we need following change: --- /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 @@ ifdVendorID + 0x234B 0x08E6 0x08E6 0x08E6 @@ -237,6 +238,7 @@ ifdProductID + 0x0000 0x2202 0x3437 0x3438 @@ -370,6 +372,7 @@ ifdFriendlyName + FSIJ USB Token Gemplus Gem e-Seal Pro Gemplus GemPC Twin Gemplus GemPC Key ------------------ This entry has been added into libccid 1.4.1 already ([r5425]). Testing Gnuk ------------ Try following to see Gnuk runs: $ gpg --card-status Personalize the Token and import keys ------------------------------------- You can personalize the token, putting your information like: Name, Login name, Sex, Languages, URL, etc., and password. 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. No, Gnuk doesn't support key generation. You need 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. For detail, please see doc/DEMO and doc/DEMO-2. Note that it make sense to preserve your keys on your computer so that you can import the keys (again) to (possibly another) Gnuk Token. In this case, you can use GnuPG's option to specify the home directory by --homedir. After creating keys by: $ gpg --gen-key ... Copy directory which contains your secret keys to new directory named : $ cp -pa $HOME/.gnupg Then, import keys by: $ gpg --edit-key While your $HOME/.gnupg now doesn't have your secret keys after import, still has them. You can again import them by: $ gpg --homedir= --edit-key Note that you *should not* save changes this time to preserve keys on your computer. The session goes like this: gpg> quit Save changes? (y/N) n Quit without saving? (y/N) y 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 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 Read-only Git Repository ======================== You can browse at http://www.gniibe.org/gitweb?p=gnuk.git;a=summary You can get it by: $ git clone git://www.gniibe.org/gnuk.git/ or $ git clone http://www.gniibe.org/git/gnuk.git/ Information on the Web ====================== Please visit: http://www.fsij.org/gnuk/ Your Contributions ================== FSIJ welcomes your contributions. Please assign your copyright to FSIJ (if possible). Foot note ========== * NUK(R) is a registered trademark owend by MAPA GmbH, Germany. --