Fix factory-reset for admin-less mode.
[gnuk/gnuk.git] / README
diff --git a/README b/README
index 6cafed5..08feaed 100644 (file)
--- a/README
+++ b/README
@@ -1,28 +1,27 @@
 Gnuk - An Implementation of USB Cryptographic Token for GnuPG
 
-                                                         Version 1.1.8
-                                                            2015-09-17
+                                                         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.8, 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 modern GnuPG with
-development version of libgcrypt.
+that the instruction of importing keys won't cause any confusion.
 
-It also supports 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,7 +47,7 @@ FAQ
 
 Q0: How Gnuk USB Token is superior than other solutions (OpenPGP
     card 2.0, YubiKey, etc.) ?
-    http://www.g10code.de/p-card.html
+    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
@@ -63,11 +62,12 @@ A0: Good points of Gnuk are:
 
 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.
+    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 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.
@@ -77,12 +77,12 @@ A3: Orthodox choice is Olimex STM32-H103.
     choice for experiment.
 
 Q4: What's version of GnuPG are you using?
-A4: In Debian GNU/Linux system, I use GnuPG modern 2.1.x in
-    experimental.
+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.
 
@@ -139,22 +139,14 @@ 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.  STM32 Nucleo F103 comes with the valiant of
-    ST-Link/V2.
+    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 eighth 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.
@@ -171,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)
@@ -182,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
@@ -256,7 +248,7 @@ External source code
 
 Gnuk is distributed with external source code.
 
-* chopstx/  -- Chopstx 0.10
+* chopstx/  -- Chopstx 1.3
 
   We use Chopstx as the kernel for Gnuk.
 
@@ -369,10 +361,10 @@ You need GNU toolchain and newlib for 'arm-none-eabi' target.
 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.25-5+5+b1
-       gcc-arm-none-eabi       15:4.9.3+svn227297-1
-       gdb-arm-none-eabi       7.7.1+dfsg-5+8
-       libnewlib-arm-none-eabi 2.2.0+git20150830.5a3d536-1
+       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.
@@ -403,18 +395,14 @@ How to install
 Olimex STM32-H103 board
 -----------------------
 
-If you are using Olimex JTAG-Tiny, type following to invoke OpenOCD:
-
-  $ openocd -f interface/ftdi/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
@@ -422,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"
 
 
 
@@ -443,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
+========================================================
 
-You need python and pyscard (python-pyscard package in Debian) or
-PyUSB 0.4.3 (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.
@@ -557,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:
 
@@ -588,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 in Gnuk 1.1.  If you have
-old code of ChibiOS/RT, you need:
+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
@@ -605,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:
 
@@ -616,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