ECC keygen
[gnuk/gnuk.git] / README
diff --git a/README b/README
index c38b7c8..3ae97b6 100644 (file)
--- a/README
+++ b/README
@@ -1,28 +1,31 @@
-************* THIS IS DEVELOPMENT BRANCH OF GNUK       *************
-************* Text written below is for release 1.0.2, *************
-************* which might not be vaild for this code   *************
-
-For those who follow Git master:
-
-We migrate from ChibiOS/RT to Chopstix.  You need:
-
-    Edit .git/config to remove chibios reference
-    git rm --cached chibios
-
-
-
 Gnuk - An Implementation of USB Cryptographic Token for GnuPG
 
-                                                         Version 1.0.2
-                                                            2013-02-15
+                                                         Version 1.1.5
+                                                            2015-06-03
                                                           Niibe Yutaka
                                      Free Software Initiative of Japan
 
+Warning
+=======
+
+This is another experimental release of Gnuk, version 1.1.5, 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
+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
@@ -55,28 +58,27 @@ 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.
+    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.
-    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) will be soon available for sale,
-    and 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.
 
 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
+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: 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).
-    Note that pcscd and libccid are optional, you can use Gnuk without them.
+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
@@ -87,18 +89,10 @@ A6: You need a target board plus a JTAG/SWD debugger.  If you just
 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:
+    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
 
@@ -112,7 +106,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
@@ -124,15 +118,27 @@ 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 a second minor release in version 1.0 series of Gnuk.
+This is third experimental release in version 1.1 series of Gnuk.
 
-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.
+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:
 
@@ -151,9 +157,8 @@ Tested features are:
        * 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
+       * Overriding key import
 
 Original features of Gnuk, tested lightly:
 
@@ -163,48 +168,33 @@ Original features of Gnuk, tested lightly:
 
 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.
+        * 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.
+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 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.
+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 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.
+Gnuk.  The pinpad support for GnuPG is only available in version 2.
 
 
 Souce code
@@ -229,10 +219,9 @@ 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.
+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
@@ -240,17 +229,14 @@ External source code
 
 Gnuk is distributed with external source code.
 
-* chibios/  -- ChibiOS/RT 2.4.3
+* chopstx/  -- Chopstx 0.04
 
-  Source code taken from: http://chibios.sourceforge.net/
+  We use Chopstx as the kernel for Gnuk.
 
-  We use ChibiOS/RT as the kernel for Gnuk.
+  Chopstx is distributed under GPLv3+ (with a special exception).
 
-  ChibiOS/RT is distributed under GPLv3+ (with a special exception
-  for unmodified code).
 
-
-* polarssl/  -- PolarSSL 1.2.6
+* polarssl/  -- PolarSSL 1.2.10
 
   Souce code taken from: http://polarssl.org/
 
@@ -275,7 +261,12 @@ Gnuk is distributed with external source code.
   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.
+  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.
@@ -297,8 +288,10 @@ 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 to yours, so that users can see it's
-not by original vendor, and it is modified version.
+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:
@@ -340,43 +333,16 @@ 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:
+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 -Os" instead of "-O2" and it will be slightly better.
-
 
 Change directory to `src':
 
@@ -394,7 +360,7 @@ Type:
 
   $ make
 
-Then, we will have "gnuk.elf".
+Then, we will have "gnuk.elf" under src/build directory.
 
 
 How to install
@@ -405,7 +371,7 @@ 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
+  $ 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:
 
@@ -420,80 +386,23 @@ Then, with another terminal, type following to write "gnuk.elf" to Flash ROM:
 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
-  $ 
+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 yet.
-
-
-STM8S Discovery Kit
--------------------
-
-If you are using FTDI-2232D module and the connection is standard, type:
+But it doesn't support option bytes handling (protection) yet.
 
-  $ 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
---------------------
+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.
 
@@ -505,7 +414,7 @@ Invoke your OpenOCD and type:
 
   $ telnet localhost 4444
   > reset halt
-  > stm32x lock 0
+  > stm32f1x lock 0
   > reset
   > shutdown
 
@@ -521,7 +430,7 @@ How to configure
 ================
 
 You need python and pyscard (python-pyscard package in Debian) or
-PyUSB (python-usb package in Debian).
+PyUSB 0.4.3 (python-usb package in Debian).
 
 (1) [pyscard] Stop scdaemon
     [PyUSB] Stop the pcsc daemon.
@@ -569,42 +478,6 @@ 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
 ------------
 
@@ -613,16 +486,15 @@ Type following command to see Gnuk runs:
   $ gpg --card-status
 
 
-Besides, there is a functinality test under test/ directory.  See
+Besides, there is a functionality test under test/ directory.  See
 test/README.
 
 
-Personalize the Token and import keys
--------------------------------------
+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
 
@@ -636,40 +508,8 @@ RSA), you can import them.
 Gnuk supports key generation, but this feature is young and should be
 considered experimental.
 
-For detail, please see doc/note/DEMO and doc/note/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
-
+For detail, please see documentation under doc/.  You can see the HTML
+version at: http://www.fsij.org/doc-gnuk/
 
 
 How to debug
@@ -704,18 +544,25 @@ See doc/note/firmware-update.
 Git Repositories
 ================
 
-You can browse at: http://www.gniibe.org/gitweb?p=gnuk.git;a=summary
+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.  If you have old code of
+ChibiOS/RT, you need:
 
-Copy is available at: http://gitorious.org/gnuk
+    Edit .git/config to remove chibios reference
+    git rm --cached chibios
 
 
 Information on the Web
@@ -723,6 +570,14 @@ 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
 ==================
@@ -733,5 +588,6 @@ to FSIJ (if possible).
 
 Foot note
 ==========
+
 * NUK(R) is a registered trademark owend by MAPA GmbH, Germany.
 --