[gnuk/gnuk.git] / README

Gnuk - An Implementation of USB Cryptographic Token for GnuPG

                                                            Version 1.0
                                                             2012-08-XX
                                                           Niibe Yutaka
                                      Free Software Initiative of Japan

What's Gnuk?
============

Gnuk is an implementation of USB cryptographic token for GNU Privacy
Guard.  Gnuk supports OpenPGP card protocol version 2, 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.
There is a solution with OpenPGP card, 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.  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 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.18-2.  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, and backported to 2.0
    branch, it will be 2.0.20).  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, 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: STLink v2 is cheap one.  We have a tool/stlinkv2.py as flash ROM
writer program.


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

This is version 1.0 release of Gnuk, after a year and eleven months
development.  While it is daily use for a year or so, some newly
introduced features (including key generation and firmware upgrade)
should be considered 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
        * Card holder certificate (read)
        * Removal of keys
          (Overriding key import is not supported,
          but you can remove all keys to import again).
        * Key generation on device side

Original features of Gnuk, tested lightly:

        * OpenPGP card serial number setup
        * Card holder certificate (write by UPDATE BINARY)
        * Upgrading with "EXTERNAL AUTHENTICATE" by reGNUal

It is known not-working well:

        * For some version of kernel and libccid, --enable-debug can't
          work well.  Please make sure to disable DEBUG option if it
          doesn't work well.

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 and Flying Stone Tiny 01 (FST-01).  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 enabling 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.

Note that you need pinpad support for GnuPG to use PIN-pad enabled
Gnuk.  The pinpad support for GnuPG is currently in the master branch
of GnuPG git repository at git.gnupg.org, and it's under evaluation.
When it will be considered stable, it will be put onto stable branch.


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

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 USB Token by Gnuk
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.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.

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

  The files include/polarssl/rsa.h, library/rsa.c,
  include/polarssl/bignum.h, and library/bignum.c are modified so that
  f_rng function returns unsigned char.

  The file library/rsa.c is modified so that it only computes things
  needed for Gnuk.

  The file library/aes.c is modified so that some constants can
  go to .sys section.


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 "FSIJ" in the string gnukStringSerial (usb_desc.c) to
yours, so that the device will say it's modified version by device
serial number.

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 "FSIJ" in the
string gnukStringSerial (usb_desc.c) 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.

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/ (which includes fix
of binutils-2.21.1) for preparation of GNU Toolchain for
'arm-none-eabi' target.  This is for GCC 4.5.

# Note that we need to link correct C library (for string functions).
# For this purpose, Makefile.in contains following line:
# 
#       MCFLAGS= -mcpu=$(MCU) -mfix-cortex-m3-ldrd
# 
# This should not be needed (as -mcpu=cortex-m3 means
# -mfix-cortex-m3-ldrd), but in practice it is needed for 
# the configuration of patch-gcc-config-arm-t-arm-elf.diff in
# summon-arm-toolchain.
# 
# In ChibiOS_2.0.8/os/ports/GCC/ARM/rules.mk, it specifies
# -mno-thumb-interwork option.  This means that you should not
# link C library which contains ARM (not Thumb) code.

Recently, there is "gcc-arm-embedded" project.  See:

    https://launchpad.net/gcc-arm-embedded/

It is based on GCC 4.6.   For version 4.6-2012-q2-update, you'd
need "-O3 -s" instead of "-O2".


Change directory to `src':

  $ cd gnuk-VERSION/src

Then, run `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

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
  $ 


Flying Stone Tiny 01
--------------------

If you are using Flying Stone Tiny 01, you need a SWD writer.  I am
using revision 946 of Simon Qian's Versaloon.

    svn checkout -r 946 http://vsprog.googlecode.com/svn/trunk/

For OpenOCD, we need unofficial patch.

See the article of Versaloon Forum:

    http://www.versaloon.com/bbs/viewtopic.php?p=16179


Type following to invoke OpenOCD:

  $ openocd -f interface/vsllink.cfg -c "transport select swd" -c "swd_mode 2" -f target/stm32f1x.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".

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

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

This entry has been added into libccid 1.4.1 already ([r5425]).


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

Type following command to see Gnuk runs:

  $ gpg --card-status


Besides, there is a functinality test under test/ directory.  See
test/README.


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.

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 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 on your computer by:

  $ gpg --gen-key
  ...

Copy directory which contains your secret keys to new directory named
<gpgdir-with-your-secret-keys>:

  $ cp -pa $HOME/.gnupg <gpgdir-with-your-secret-keys>

Then, import keys by:

  $ gpg --edit-key <YOUR-KEYID>

While your $HOME/.gnupg now doesn't have your secret keys after
import, <gpgdir-with-your-secret-keys> still has them.  You can again
import them by:

  $ gpg --homedir=<gpgdir-with-your-secret-keys> --edit-key <YOUR-KEYID>

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


Firmware update
===============

See doc/firmware-update.


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