Gnuk - software for GPG USB Token

							    Version 0.5
							     2010-12-13
						           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 will be with a
USB Token by Gnuk everywhere.


Release notes
=============

This is sixth release of Gnuk.  While it works well for specific
usages, it is still 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).

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.

Not (yet) supported feature(s):

	* card holder certificate (its size matters (> 1KiB?), if we support)

Not supported feature(s):

	* Overriding key import.  You need to remove all keys first.


Targets
=======

We use Olimex STM32-H103 board.  We also use STM32 part of STM8S
Discovery Kit.

With DfuSe support, CQ STARM 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 protect 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.


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.  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.


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.

* 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/esden/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

In the make process, it takes time for the command of

   dd if=/dev/random bs=1 of=random_bits count=1024

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
==========

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
  $ 


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 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.


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, 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 @@
 
 	<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>
------------------


Testing Gnuk
------------

Try following to see Gnuk runs:

  $ gpg --card-status


For more, see doc/DEMO.



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 get it by:

  $ git clone http://www.gniibe.org/git/gnuk.git/


Information on the Web
======================

Please see: 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.
--