bug fix of OPENPGP.3 singing

[gnuk/gnuk.git] / README

Gnuk - An Implementation of USB Cryptographic Token for GnuPG

                                                          Version 1.1.4
                                                             2014-12-15
                                                           Niibe Yutaka
                                      Free Software Initiative of Japan

Warning
=======

This is another experimental release of Gnuk, version 1.1.4, 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 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, 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.  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 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

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:

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

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.

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

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

* chopstx/  -- Chopstx 0.04

  We use Chopstx as the kernel for Gnuk.

  Chopstx is distributed under GPLv3+ (with a special exception).


* polarssl/  -- PolarSSL 1.2.10

  Souce code taken from: http://polarssl.org/

  We use PolarSSL for RSA computation, and AES encryption/decryption.

  PolarSSL is distributed under GPLv2+.  We use PolarSSL under GPLv3
  as our options.

  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.

  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.

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

  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.

There is "gcc-arm-embedded" project.  See:

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


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" under src/build directory.


How to install
==============

Olimex STM32-H103 board
-----------------------

If you are using Olimex JTAG-Tiny, type following to invoke OpenOCD:

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

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

OpenOCD 0.6.1 now supports ST-Link/V2.  We can use it:

  $ openocd -f interface/stlink-v2.cfg -f target/stm32f1x_stlink.cfg

But it doesn't support option bytes handling (protection) yet.


STBee
-----

Reset the board with "USER" switch pushed.  Type following to write
to flash:

  # cd ../tool
  # ./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
-------------

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.


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

Type following command to see Gnuk runs:

  $ gpg --card-status


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


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

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

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/note/firmware-update.


Git Repositories
================

Please use: http://gitorious.org/gnuk

You can get it by:
 
    $ git clone git://gitorious.org/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

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