Firmware update feature
=======================

The firmware update feature of Gnuk is experimental.  Please be
careful using that.

Note that updating firmware, all data objects and keys will be
removed.  There is _no way_ to preserve those data.


Preparation
===========

In addition to settings of Gnuk, I create a file
/etc/udev/rules.d/92-gnuk.rules::

   # For updating firmware, permission settings are needed.
   
   SUBSYSTEMS=="usb", ATTRS{idVendor}=="234b", ATTRS{idProduct}=="0000", \
       ENV{ID_USB_INTERFACES}=="*:ff0000:*", GROUP="pcscd"


While I am a member of group "pcscd" in /etc/group.

This is needed for reGNUal, the firmware update program.


Registering a public key for firmware update
============================================

You need to register a public key to update the firmware.  It should
be RSA 2048-bit.

One way to extract public key data is by using "gpg-connect-agent"
command connecting gpg-agent.

We can examine key information of gpg-agent by "KEYINFO" command.
Here is my example::

   $ gpg-connect-agent "KEYINFO --list" /bye
   S KEYINFO 65F67E742101C7FE6D5B33FCEFCF4F65EAF0688C T D276000124010200F517000000010000 OPENPGP.2 - - -
   S KEYINFO 101DE7B639FE29F4636BDEECF442A9273AFA6565 T D276000124010200F517000000010000 OPENPGP.1 - - -
   S KEYINFO 5D6C89682D07CCFC034AF508420BF2276D8018ED T D276000124010200F517000000010000 OPENPGP.3 - - -
   OK

I have three keys in my token.

With the script below, I extract public key of the keygrip
5D6C89682D07CCFC034AF508420BF2276D8018ED into the file: 5D6C8968.bin::

   $ ./get_raw_public_key.py 5D6C89682D07CCFC034AF508420BF2276D8018ED

(The script is available in the directory gnuk/tool.  Please note that
it was written in the early stage of the development.  The quality of
the code is somewhat questionable.)


Then, we can put the data of public key into token by::

   $ tool/gnuk_put_binary_libusb.py -k 0 5D6C8968.bin


Invoking firmware update
========================

We specify reGNUal binary and Gnuk binary.

  $ ../tool/gnuk_upgrade.py ../regnual/regnual.bin gnuk.bin 


Two or more tokens
==================

Currently, GnuPG doesn't support multiple devices connected to the
host.

In order to update the firmware of a TARGET token, we use GnuPG to
authenticate with public key.  It is assumed that you have another
AUTH token for this.  This situation is somewhat complicated.

What I do is:
(1) Don't run PC/SC daemon::

  # /etc/init.d/pcscd stop

(2) To make sure, kill scdaemon::

  $ killall -9 scdaemon

(3) Insert the AUTH token to USB, and use it::

  $ gpg --card-status

(4) Insert the TARGET token to USB (after scdaemon communicates AUTH
    token), and invoke gnuk_upgrade.py.
    In this situation, gnuk_upgrade.py tries to connect one of tokens,
    but a connection to the AUTH token will fail because scdaemon is
    connecting to that device, and will be expected to connect to the
    TARGET token succesufully, instead.
--