Increase CCID thread stack size by 0x20 for newer GCC.
[gnuk/gnuk.git] / README
diff --git a/README b/README
index 3bbf226..b47a450 100644 (file)
--- a/README
+++ b/README
@@ -1,25 +1,34 @@
 Gnuk - An Implementation of USB Cryptographic Token for GnuPG
 
-                                                         Version 1.1.0
-                                                            2013-12-20
+                                                         Version 1.2.2
+                                                            2016-10-15
                                                           Niibe Yutaka
                                      Free Software Initiative of Japan
 
-Warning
-=======
+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.
 
-This is an experimental release of Gnuk 1.1.0, 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 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 an implementation of USB cryptographic token for GNU Privacy
-Guard.  Gnuk supports OpenPGP card protocol version 2, and it runs on
+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
@@ -37,9 +46,9 @@ 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/
+    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).
@@ -52,21 +61,24 @@ A0: Good points of Gnuk are:
            "for Free Software"; Gnuk supports GnuPG.
 
 Q1: What kind of key algorithm is supported?
-A1: Gnuk version 1 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.
     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.12-7 and gnupg-agent
-    2.0.20-1.
+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: I don't use them, pcscd and libccid are optional, you can use Gnuk
@@ -84,13 +96,10 @@ 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
+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:
 
@@ -106,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
@@ -114,21 +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: ST-Link/V2 is cheap one.  We have a tool/stlinkv2.py as flash ROM
-    writer program.
+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;
 
-Release notes
-=============
+    Please edit this line to:
 
-This is an experimental release in version 1.1 series of Gnuk.
+        OnlyShowIn=
 
-While it is daily use for a year and a half, some newly introduced
-features (including key generation and firmware upgrade) should be
-considered experimental.
+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.
 
-Tested features are:
+
+Tested features
+===============
+
+Gnuk is tested by test suite.  Please see the test directory.
 
        * Personalization of the card
          * Changing Login name, URL, Name, Sex, Language, etc.
@@ -145,10 +163,10 @@ Tested features are:
        * Modify with pin pad
        * Card holder certificate (read)
        * Removal of keys
-       * Key generation on device side
+       * Key generation on device side for RSA-2048
        * Overriding key import
 
-Original features of Gnuk, tested lightly:
+Original features of Gnuk, tested manually lightly:
 
        * OpenPGP card serial number setup
        * Card holder certificate (write by UPDATE BINARY)
@@ -156,36 +174,48 @@ Original features of Gnuk, tested lightly:
 
 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.
+        * 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, 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 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.
+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.
 
 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.
 
 
+Build system and Host system
+============================
+
+Makefile is written for GNU make.  You need Bash 4.x for configure.
+
+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
 ==========
 
@@ -218,14 +248,14 @@ External source code
 
 Gnuk is distributed with external source code.
 
-* chopstx/  -- Chopstx 0.04
+* chopstx/  -- Chopstx 1.3
 
   We use Chopstx as the kernel for Gnuk.
 
   Chopstx is distributed under GPLv3+ (with a special exception).
 
 
-* polarssl/  -- PolarSSL 1.2.10
+* polarssl/  -- based on PolarSSL 1.2.10 (now mbedTLS)
 
   Souce code taken from: http://polarssl.org/
 
@@ -271,7 +301,7 @@ Gnuk is distributed with external source code.
 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 the source code.
@@ -328,10 +358,16 @@ How to compile
 
 You need GNU toolchain and newlib for 'arm-none-eabi' target.
 
-There is "gcc-arm-embedded" project.  See:
+On Debian we can install the packages of gcc-arm-none-eabi,
+gdb-arm-none-eabi and its friends.  I'm using:
 
-    https://launchpad.net/gcc-arm-embedded/
+       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':
 
@@ -345,7 +381,8 @@ 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
 
@@ -358,76 +395,26 @@ How to install
 Olimex STM32-H103 board
 -----------------------
 
-If you are using Olimex JTAG-Tiny, type following to invoke OpenOCD:
+If you are using Olimex JTAG-Tiny, type following to invoke OpenOCD
+and write "gnuk.elf" to Flash ROM:
 
-  $ openocd -f interface/olimex-jtag-tiny.cfg -f board/olimex_stm32_h103.cfg
+  $ openocd -f interface/ftdi/olimex-jtag-tiny.cfg \
+            -f board/olimex_stm32_h103.cfg \
+            -c "program build/gnuk.elf verify reset exit"
 
-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
-  $ 
+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:
+If you are using Flying Stone Tiny 01, you need a SWD writer.
 
-  $ telnet localhost 4444
-  > reset halt
-  > flash write_image erase gnuk.elf
-  > reset
-  > exit
-  $ 
+OpenOCD 0.9.0 now supports ST-Link/V2.  We can use it like:
 
-OpenOCD 0.6.1 now supports ST-Link/V2.  We can use it:
+  $ openocd -f interface/stlink-v2.cfg -f target/stm32f1x.cfg \
+            -c "program build/gnuk.elf verify reset exit"
 
-  $ openocd -f interface/stlink-v2.cfg -f target/stm32f1x_stlink.cfg
-
-But it doesn't support option bytes handling (protection) yet.
-
-
-STM8S Discovery Kit
--------------------
-
-If you are using FTDI-2232D module and the connection is standard, type:
-
-  $ openocd -f interface/openocd-usb.cfg -f target/stm32f1x.cfg
-
-Initially, the flash ROM of the chip is protected.  you need to do:
-
-  $ telnet localhost 4444
-  > reset halt
-  > stm32f1x 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.
 
 
 STBee
@@ -445,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
-  > stm32f1x 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
+========================================================
+
+This is completely optional.
 
-You need python and pyscard (python-pyscard package in Debian) or
-PyUSB (python-usb package in Debian).
+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.
@@ -484,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
   ...
 
@@ -492,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
   ...
@@ -559,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:
 
@@ -579,13 +576,22 @@ See doc/note/firmware-update.
 Git Repositories
 ================
 
-Please use: http://gitorious.org/gnuk
+Please use: https://anonscm.debian.org/cgit/gnuk/gnuk/
+
+You can get it by:
+    $ git clone git://anonscm.debian.org/gnuk/gnuk/gnuk.git
 
 It's also available at: www.gniibe.org
-You can browse at: http://www.gniibe.org/gitweb?p=gnuk.git;a=summary
+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:
 
-We migrated from ChibiOS/RT to Chopstix.  If you have old code of
-ChibiOS/RT, you need:
+  $ 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
@@ -596,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.
 --