Gnuk - software for GPG USB Token

							    Version 0.2
							     2010-09-11
						           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, always, everywhere.  I will be with a USB
Token by Gnuk everywhere.


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

This is second release of Gnuk.  While it works somehow, 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 both of key for digital signing and key for
          decryption.

	* PSO: Digital Signature

	* PSO: Decipher

It is known not-working well:

	* Key import multiple times

	* Changing value of password status bytes (0x00C4).


Targets
=======

We use Olimex STM32-H103 board.

I think that it could run on Olimex STM32-P103, STBee, or STBee mini
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+).


External source code
====================

Gnuk is distributed with external source code.

* ChibiOS_2.0.2/  -- ChibiOS/RT 2.0.2

  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.

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


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.

  $ cd gnuk-VERSION/src

Edit the Makefile.  Comment out the line:
----------------
ENABLE_DEBUG=1
----------------

if you don't want to debug Gnuk.

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

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
  $ 

If you compiled with ENABLE_DEBUG=1, 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.

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

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


Development history
===================

Initially, the development was started with a copy of the files in
ChibiOS_2.0.2/demos/ARMCM3-STM32F103-GCC/*, Makefile, linker script,
and header files (chconf.h, halconf.h, and mcuconf.h).

Since this is the initial release, some garbages may still remain.
--