Fix factory-reset for admin-less mode.
[gnuk/gnuk.git] / README
diff --git a/README b/README
index 08891bb..08feaed 100644 (file)
--- a/README
+++ b/README
@@ -1,29 +1,27 @@
 Gnuk - An Implementation of USB Cryptographic Token for GnuPG
 
-                                                         Version 1.1.6
-                                                            2015-07-21
+                                                         Version 1.2.4
+                                                            2017-05-12
                                                           Niibe Yutaka
                                      Free Software Initiative of Japan
 
-Warning
-=======
+Release Notes
+=============
 
-This is another experimental release of Gnuk, version 1.1.6, which has
+This is the release of Gnuk, version 1.2.4, 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 ECDSA (with NIST P256 and secp256k1), EdDSA, and ECDH
-(with NIST P256, secp256k1, and Curve25519), but this ECC feature is
-pretty much experimental, and it requires development version of GnuPG
-with newest version of libgcrypt (Further, for Curve25519, it requires
-additional patches by me).
+that the instruction of importing keys won't cause any confusion.
 
-It also support RSA-4096 experimentally, but users should know that it
-takes more than 8 second to sign/decrypt.
+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.
 
-You will not able to keep using Curve25519 keys, as the key format is
-subject to change.
+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?
@@ -48,9 +46,9 @@ 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/
+    card 2.0, YubiKey, etc.) ?
+    https://www.g10code.de/p-card.html
+    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).
@@ -63,25 +61,28 @@ A0: Good points of Gnuk are:
            "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.
+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.
     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.18 in
+    unstable.
 
 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.
+    Token without them.
     I tested pcscd 1.5.5-4 and libccid 1.3.11-2 which were in Debian
     squeeze.
 
@@ -94,8 +95,11 @@ 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: 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:
 
@@ -134,24 +138,15 @@ Ac: That's because gnome-keyring-daemon interferes GnuPG.  Please
 
 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.
-
-
+    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 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/ECDH, key generation and firmware upgrade)
-should be considered experimental.  ECDSA/EdDSA/ECDH is really
-experimental.  Further, ECDH on Curve25519 is much experimental.  You
-won't be able to keep using the key, since the key format of GnuPG is
-not defined and it's subject to change.
+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.
@@ -168,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)
@@ -179,12 +174,12 @@ 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
@@ -197,12 +192,12 @@ 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.
+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.
@@ -253,7 +248,7 @@ External source code
 
 Gnuk is distributed with external source code.
 
-* chopstx/  -- Chopstx 0.07
+* chopstx/  -- Chopstx 1.3
 
   We use Chopstx as the kernel for Gnuk.
 
@@ -306,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.
@@ -363,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.28-4+9+b2
+       gcc-arm-none-eabi       15:5.4.1+svn241155-1
+       gdb-arm-none-eabi       7.12-6+9+b2
+       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':
 
@@ -394,18 +395,14 @@ 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/ftdi/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
@@ -413,9 +410,10 @@ Flying Stone Tiny 01
 
 If you are using Flying Stone Tiny 01, you need a SWD writer.
 
-OpenOCD 0.9 now supports ST-Link/V2.  We can use it:
+OpenOCD 0.9.0 now supports ST-Link/V2.  We can use it like:
 
-  $ openocd -f interface/stlink-v2.cfg -f target/stm32f1x_stlink.cfg
+  $ openocd -f interface/stlink-v2.cfg -f target/stm32f1x.cfg \
+            -c "program build/gnuk.elf verify reset exit"
 
 
 
@@ -434,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 0.4.3 (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.
@@ -548,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,14 +587,14 @@ 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
+    $ git submodule update --init
 
-We have migrated from ChibiOS/RT to Chopstx.  If you have old code of
+Gnuk 1.0 uses ChibiOS/RT, and then, we have migrated from to Chopstx
+in the development phase of Gnuk 1.1.  If you have old code of
 ChibiOS/RT, you need:
 
-    Edit .git/config to remove chibios reference
-    git rm --cached chibios
+    Edit .git/config to remove chibios reference and
+    git rm --cached chibios
 
 
 Information on the Web
@@ -596,7 +604,7 @@ Please visit: http://www.fsij.org/gnuk/
 
 Please see the FST-01 support pages:
 
-    http://www.gniibe.org/category/fst-01.html
+    https://www.gniibe.org/category/fst-01.html
 
 Please consider to join Gnuk-users mailing list:
 
@@ -607,7 +615,7 @@ Your Contributions
 ==================
 
 FSIJ welcomes your contributions.  Please assign your copyright
-to FSIJ (if possible).
+to FSIJ (if possible), as I do.
 
 
 Foot note