Increase CCID thread stack size by 0x20 for newer GCC.
[gnuk/gnuk.git] / README
diff --git a/README b/README
index e25625c..b47a450 100644 (file)
--- a/README
+++ b/README
-Gnuk - software for GnuPG USB Token
+Gnuk - An Implementation of USB Cryptographic Token for GnuPG
 
-                                                          Version 0.18
-                                                            2012-05-15
+                                                         Version 1.2.2
+                                                            2016-10-15
                                                           Niibe Yutaka
                                      Free Software Initiative of Japan
 
+Release Notes
+=============
+
+This is the release of Gnuk, version 1.2.2, which has major
+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 EdDSA, ECDSA (with NIST P256 and secp256k1), and
+ECDH (with X25519, NIST P256 and secp256k1), but this ECC feature is
+somehow experimental, and it requires modern GnuPG 2.1 with libgcrypt
+1.7.0 or later.
+
+It also supports RSA-4096, but users should know that it takes more
+than 8 seconds to sign/decrypt.  Key generation of RSA-4096 just fails,
+because the device doesn't have enough memory.
+
+
 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
+Gnuk is an implementation of USB cryptographic token for GNU Privacy
+Guard.  Gnuk supports OpenPGP card protocol version 3, 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.
+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.  I am with a USB
-Token by "Gnuk", always, everywhere.
+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.) ?
+    card 2.0, YubiKey, etc.) ?
     http://www.g10code.de/p-card.html
-    http://www.privacyfoundation.de/crypto_stick/
-A0: IMRHO, not quite, since there is no ready-to-use out-of-box Gnuk
-    product yet.  (It is welcome for me that some vendor will
-    manufacture Gnuk USB Token.  Even I can help design of hardware,
-    if needed.)
-    Good points for Gnuk are:
+    https://www.yubico.com/
+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.
+      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 only supports 2048-bit RSA.
+A1: Gnuk version 1.0 only supports RSA-2048.
+    Gnuk version 1.2.x supports 255-bit EdDSA, as well as RSA-4096.
+    (Note that 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. 
+A2: It takes a second and a half or so for RSA-2048. 
+    It takes more than 8 secondd for RSA-4096.
 
 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.
+    FST-01 (Flying Stone Tiny 01) is available for sale, and it is a
+    kind of the best choice, hopefully.
+    If you have a skill of electronics, STM32 Nucleo F103 is the best
+    choice for experiment.
 
 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.14-2 (in sid).  With older versions, you can only sign with SHA1.
-    See: http://www.fsij.org/gnuk/gnupg2-fixes-needed
+A4: In Debian GNU/Linux system, I use GnuPG modern 2.1.13 in
+    experimental.
 
 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).
+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 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.
+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.
 
 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
+A8: STM32 Nucleo F103 costs about $10 USD.
 
 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).  When your newly
-    inserted token is not found by GnuPG, try killing scdaemon and let
-    it to be invoked again.  I do:
-      $ killall -9 scdaemon
+A9: Older 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
+
+        $ 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
@@ -97,7 +115,7 @@ Aa: You need to deactivate seahorse-agent and gnome-keyring, but use
 
       $ 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?
+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
@@ -105,19 +123,30 @@ Ab: That's because gnome-keyring-daemon interferes GnuPG.  Type:
     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: Perhaps, you can use a part of STM32F4 Discovery Kit as SWD
-    debugger.  It seems that there is a free software tool for that.
+Qc: With GNOME 3.x (x >= 8?), I can't use Gnuk Token at all.  Why?
+Ac: That's because gnome-keyring-daemon interferes GnuPG.  Please
+    disable the invocation of gnome-keyring-daemon.  In Debian
+    wheezy, it's in the files /etc/xdg/autostart/gnome-keyring-ssh.desktop
+    and /etc/xdg/autostart/gnome-keyring-gpg.desktop.
+    We have a line something like:
 
+        OnlyShowIn=GNOME;Unity;MATE;
+
+    Please edit this line to:
+
+        OnlyShowIn=
+
+Qd: Do you know a good SWD debugger to connect FST-01 or something?
+Ad: ST-Link/V2 is cheap one.  We have a tool/stlinkv2.py as flash ROM
+    writer program.  STM32 Nucleo F103 comes with the valiant of
+    ST-Link/V2.  However, the firmware of ST-Link/V2 is proprietary.
+    Now, I develop BBG-SWD, SWD debugger by BeagleBone Green.
 
-Release notes
-=============
 
-This is nineteenth release of Gnuk.  In this release, the usage of USB
-device ID by FSIJ is clarified.  While it works well for specific
-usages and it is considered stable, it is still somewhat experimental.
+Tested features
+===============
 
-Tested features are:
+Gnuk is tested by test suite.  Please see the test directory.
 
        * Personalization of the card
          * Changing Login name, URL, Name, Sex, Language, etc.
@@ -132,57 +161,59 @@ Tested features are:
        * Changing value of password status bytes (0x00C4): forcesig
        * Verify with pin pad
        * Modify with pin pad
-       * Card holder certificate
-       * Removal of keys (Overriding key import is not supported,
-         but you can remove all keys to import again).
+       * Card holder certificate (read)
+       * Removal of keys
+       * Key generation on device side for RSA-2048
+       * Overriding key import
 
-It is known not-working well:
+Original features of Gnuk, tested manually lightly:
 
-       * 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.
+       * OpenPGP card serial number setup
+       * Card holder certificate (write by UPDATE BINARY)
+       * Upgrading with "EXTERNAL AUTHENTICATE" by reGNUal
 
-Not supported feature(s):
+It is known not-working well:
 
-       * Key generation on device side
+        * It is known that the specific combination of libccid 1.4.1
+         (or newer) with libusb 1.0.8 (or older) had 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.
+We use Olimex STM32-H103 board and Flying Stone Tiny 01 (FST-01).
 
-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
+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 enable read protection using JTAG debugger.
+and enabling read protection using JTAG debugger.
+
+For experimental 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.
 
-I think that it could run on Olimex STM32-P103, or other boards with
-STM32F103.  Besides, we are porting it to STM32 Primer 2.
+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.
 
-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.
+Build system and Host system
+============================
 
-Recently, "DnDpinentry" support is added.  This is using usual file
-manager for pinentry.  User does "drag and drop" folders and it will
-be pin entry.  This feature doesn't require any additional hardware.
-See doc/settings-for-DnDpinentry for your desktop configuration.
+Makefile is written for GNU make.  You need Bash 4.x for configure.
 
-Note that you need pinpad support for GnuPG, it's 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.
+If your bash is not installed as /bin/bash, you need to run configure
+script prepending 'bash' before './configure'.
+
+Some tools are written in Python.  If your Python is not installed as
+/usr/bin/python, please prepend 'python' for your command invocation.
+Python 2.7 and PyUSB 0.4.3 is assumed.
 
 
 Souce code
@@ -190,6 +221,11 @@ 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
 =======
@@ -198,14 +234,13 @@ 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.
+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 acess everything on the Token, regardless of its
-protections.  Private keys, and other information should be protected
-properly.
+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
@@ -213,34 +248,69 @@ External source code
 
 Gnuk is distributed with external source code.
 
-* ChibiOS_2.0.8/  -- ChibiOS/RT 2.0.8
+* chopstx/  -- Chopstx 1.3
 
-  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.
+  We use Chopstx as the kernel for Gnuk.
 
-* polarssl-0.14.0/  -- PolarSSL 0.14.0
+  Chopstx is distributed under GPLv3+ (with a special exception).
 
-  Taken from http://polarssl.org/
-  We use PolarSSL for RSA computation, AES encryption/decryption
-  and SHA-1 computation.
+
+* polarssl/  -- based on PolarSSL 1.2.10 (now mbedTLS)
+
+  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
+When you have a vendor 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 source code.
+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.
+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:
@@ -264,26 +334,23 @@ with Gnuk under one of following conditions:
       please use that number for your device.
       (There a file 'GNUK_SERIAL_NUMBER' in the official release.)
 
-FSIJ could permit companies or business entities 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 permission.
+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.  When you modify Gnuk, please
-replace "FSIJ" in the string gnukStringSerial (usb_desc.c) to yours.
+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, libccid version >= 1.3.11 is recommended.
-
-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.
+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
@@ -291,24 +358,16 @@ 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.
-
-# 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.
+On Debian we can install the packages of gcc-arm-none-eabi,
+gdb-arm-none-eabi and its friends.  I'm using:
+
+       binutils-arm-none-eabi  2.27-9+9
+       gcc-arm-none-eabi       15:5.4.1+svn241155-1
+       gdb-arm-none-eabi       7.11.1-2+9+b1
+       libnewlib-arm-none-eabi 2.4.0.20160527-2
 
+Or else, see https://launchpad.net/gcc-arm-embedded for preparation of
+GNU Toolchain for 'arm-none-eabi' target.
 
 Change directory to `src':
 
@@ -322,11 +381,12 @@ 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:
+
+Then, type:
 
   $ make
 
-Then, we will have "gnuk.elf".
+Then, we will have "gnuk.elf" under src/build directory.
 
 
 How to install
@@ -335,92 +395,36 @@ 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
+If you are using Olimex JTAG-Tiny, type following to invoke OpenOCD
+and write "gnuk.elf" to Flash ROM:
 
-Then, with another terminal, type following to write "gnuk.elf" to Flash ROM:
+  $ openocd -f interface/ftdi/olimex-jtag-tiny.cfg \
+            -f board/olimex_stm32_h103.cfg \
+            -c "program build/gnuk.elf verify reset exit"
 
-  $ telnet localhost 4444
-  > reset halt
-  > flash write_image erase gnuk.elf
-  > reset
-  > exit
-  $ 
+Command invocation is assumed in src/ directory.
 
 
 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
-  $ 
+If you are using Flying Stone Tiny 01, you need a SWD writer.
 
-and re-connect the board.  Note that power-off / power-on sequence is
-required to reset flash ROM.
+OpenOCD 0.9.0 now supports ST-Link/V2.  We can use it like:
 
-Then, invoke OpenOCD again and telnet to connect OpenCD and write
-image as above example of Olimex STM32-H103.
+  $ openocd -f interface/stlink-v2.cfg -f target/stm32f1x.cfg \
+            -c "program build/gnuk.elf verify 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 and STBee Mini
---------------------
+STBee
+-----
 
 Reset the board with "USER" switch pushed.  Type following to write
 to flash:
 
   # cd ../tool
-  # ./dfuse.py ../src/gnuk.hex
+  # ./dfuse.py ../src/build/gnuk.hex
 
 Then, reset the board.
 
@@ -428,27 +432,33 @@ Then, reset the board.
 How to protect flash ROM
 ========================
 
-Invoke your OpenOCD and type:
+To protect, invoke OpenOCD like (for FST-01):
 
-  $ telnet localhost 4444
-  > reset halt
-  > stm32x lock 0
-  > reset
-  > shutdown
+  $ openocd -f interface/stlink-v2.cfg -f target/stm32f1x.cfg \
+            -c init -c "reset halt" -c "stm32f1x lock 0" -c reset -c exit
 
 After power-off / power-on sequence, the contents of flash ROM cannot
 be accessible from JTAG debugger.
 
+Unprotecting is:
+
+  $ openocd -f interface/stlink-v2.cfg -f target/stm32f1x.cfg \
+            -c init -c "reset halt" -c "stm32f1x unlock 0" -c reset -c exit
+
+Upon unprotection, flash is erased.
+
 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.
+to access the contents, even if it's protected.  If you really want to
+protect, killing DfuSe and accessing by JTAG debugger is recommended.
 
 
-How to configure
-================
+(Optional) Configure serial number and X.509 certificate
+========================================================
 
-You need python and pyscard (python-pyscard package in Debian) or
-PyUSB (python-usb package in Debian).
+This is completely optional.
+
+For this procedure, 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.
@@ -456,7 +466,7 @@ PyUSB (python-usb package in Debian).
 If scdaemon is running, please kill it, or you will get "Smartcard
 Exception" by "Sharing violation".
 
-  $ killall -9 scdaemon
+  $ gpg-connect-agent "SCD KILLSCD" "SCD BYE" /bye
 
 In case of PyUSB tool, you need to stop pcscd.
 
@@ -467,7 +477,7 @@ In case of PyUSB tool, you need to stop pcscd.
 
 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
+  $ EMAIL=<YOUR-EMAIL-ADDRESS> ../tool/gnuk_put_binary_usb.py -s ../GNUK_SERIAL_NUMBER
   Writing serial number
   ...
 
@@ -475,7 +485,7 @@ If you use fixed serial number in the file 'GNUK_SERIAL_NUMBER', you can do:
 
 If you have card holder certificate binary file, you can do:
 
-  $ ../tool/gnuk_put_binary.py ../../<YOUR-CERTIFICATE>.bin
+  $ ../tool/gnuk_put_binary_usb.py ../../<YOUR-CERTIFICATE>.bin
   ../../<YOUR-CERTIFICATE>.bin: <LENGTH-OF-YOUR-CERTIFICATE>
   Updating card holder certificate
   ...
@@ -496,100 +506,38 @@ virtual COM port by:
 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
 ------------
 
-Try following to see Gnuk runs:
+Type following command to see Gnuk runs:
 
   $ gpg --card-status
 
 
-Personalize the Token and import keys
--------------------------------------
+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, etc., and password.  To do so, GnuPG
-command is:
+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.
 
-No, Gnuk doesn't support key generation.  You need 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.
-
-For detail, please see doc/DEMO and doc/DEMO-2.
+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.
 
-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 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
+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
@@ -604,6 +552,10 @@ Inside GDB, we can connect OpenOCD by:
 
   (gdb) target remote localhost:3333
 
+or
+
+  (gdb) target extended-remote localhost:3333
+
 
 You can see the output of PCSCD:
 
@@ -615,19 +567,34 @@ You can observe the traffic of USB using "usbmon".  See the file:
 linux/Documentation/usb/usbmon.txt
 
 
-Read-only Git Repository
-========================
+Firmware update
+===============
 
-You can browse at http://www.gniibe.org/gitweb?p=gnuk.git;a=summary
+See doc/note/firmware-update.
+
+
+Git Repositories
+================
+
+Please use: https://anonscm.debian.org/cgit/gnuk/gnuk/
 
 You can get it by:
+    $ git clone git://anonscm.debian.org/gnuk/gnuk/gnuk.git
 
-  $ git clone git://www.gniibe.org/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
 
-or
+I put Chopstx as a submodule of Git.  Please do this:
 
-  $ git clone http://www.gniibe.org/git/gnuk.git/
+  $ git submodule init
+  $ git submodule update
 
+We have migrated from ChibiOS/RT to Chopstx in Gnuk 1.1.  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
@@ -635,15 +602,24 @@ Information on the Web
 
 Please visit: http://www.fsij.org/gnuk/
 
+Please see the FST-01 support pages:
+
+    http://www.gniibe.org/category/fst-01.html
+
+Please consider to join Gnuk-users mailing list:
+
+    https://lists.alioth.debian.org/mailman/listinfo/gnuk-users
+
 
 Your Contributions
 ==================
 
 FSIJ welcomes your contributions.  Please assign your copyright
-to FSIJ (if possible).
+to FSIJ (if possible), as I do.
 
 
 Foot note
 ==========
+
 * NUK(R) is a registered trademark owend by MAPA GmbH, Germany.
 --