improve stlinkv2.py
[gnuk/gnuk.git] / README
diff --git a/README b/README
index fb52745..3ae97b6 100644 (file)
--- a/README
+++ b/README
+Gnuk - An Implementation of USB Cryptographic Token for GnuPG
+
+                                                         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 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, 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.  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.) ?
+    http://www.g10code.de/p-card.html
+    http://www.privacyfoundation.de/crypto_stick/
+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 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 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.
+    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.12-7 and gnupg-agent
+    2.0.20-1.
+
+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.
+    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
+    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.
+
+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.  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
+
+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
+    gpg-agant for the role of ssh-agent.  For gnome-keyring please do:
+
+      $ gconftool-2 --type bool --set /apps/gnome-keyring/daemon-components/ssh false
+
+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
+
+    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.
+
+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 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, 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:
+
+       * Personalization of the card
+         * Changing Login name, URL, Name, Sex, Language, etc.
+       * Password handling (PW1, RC, PW3)
+       * Key import for three types:
+         * key for digital signing
+         * key for decryption
+         * key for authentication
+       * PSO: Digital Signature
+       * PSO: Decipher
+       * INTERNAL AUTHENTICATE
+       * Changing value of password status bytes (0x00C4): forcesig
+       * Verify with pin pad
+       * Modify with pin pad
+       * Card holder certificate (read)
+       * Removal of keys
+       * Key generation on device side
+       * Overriding key import
+
+Original features of Gnuk, tested lightly:
+
+       * OpenPGP card serial number setup
+       * Card holder certificate (write by UPDATE BINARY)
+       * Upgrading with "EXTERNAL AUTHENTICATE" by reGNUal
+
+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.
+
+
+Targets
+=======
+
+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 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.
+
+
 Souce code
 ==========
 
-Initially, it is copy of ChibiOS_2.0.2/demos/ARMCM3-STM32F103-GCC/*.
+Gnuk source code is under src/ directory.
 
-External source
-===============
+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
+=======
+
+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 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 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
+====================
+
+Gnuk is distributed with external source code.
+
+* chopstx/  -- Chopstx 0.04
+
+  We use Chopstx as the kernel for Gnuk.
+
+  Chopstx is distributed under GPLv3+ (with a special exception).
+
+
+* polarssl/  -- PolarSSL 1.2.10
+
+  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.
 
-* ChibiOS_2.0.2
-Taken from http://chibios.sourceforge.net/
-Note that CRLF is converted to LF in this repository.
+  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.
 
-* STM32_USB-FS-Device_Driver
-Taken from http://github.com/robots/STM32.git
 
-* USBCDC
-Taken from http://github.com/robots/STM32.git
+USB vendor ID and product ID (USB device ID)
+============================================
 
+When you have a vender 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.
 
-HOWTO RUN
+When you are modifing Gnuk and installing the binary to device, you
+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:
+
+  * For everyone for experimental purpose:
+
+    - You must not distribute a binary with FSIJ's USB device ID, but
+      must use the binary by yourself only for your experiment.  Note
+      that "Distributing binary" includes distributing a device which
+      holds the binary.
+
+  * For general individuals:
+
+    - You must use your Gnuk device with a card serial number which is
+      *not* by FSIJ.  Easy one would be a card serial number generated
+      by chip unique ID.
+
+  * For individuals with explicit permission from FSIJ.
+
+    - You should have an assigned card serial number by FSIJ,
+      please use that number for your device.
+      (There a file 'GNUK_SERIAL_NUMBER' in the official release.)
+
+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.  Please replace vendor string
+and possibly product string to yours, when you modify Gnuk.
+
+
+Host Requirements
 =================
 
-$ openocd -f interface/olimex-jtag-tiny.cfg -f board/olimex_stm32_h103.cfg
+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
+==============
+
+You need GNU toolchain and newlib for 'arm-none-eabi' target.
+
+There is "gcc-arm-embedded" project.  See:
+
+    https://launchpad.net/gcc-arm-embedded/
+
+
+Change directory to `src':
+
+  $ cd gnuk-VERSION/src
+
+Then, run `configure':
+
+  $ ./configure --vidpid=<VID:PID>
+
+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:
+
+  $ make
 
-$ arm-none-eabi-gdb --annotate=3 gnuk.elf
+Then, we will have "gnuk.elf" under src/build directory.
+
+
+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
+
+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
+  $ 
+
+
+Flying Stone Tiny 01
+--------------------
+
+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 (protection) yet.
+
+
+STBee
+-----
+
+Reset the board with "USER" switch pushed.  Type following to write
+to flash:
+
+  # cd ../tool
+  # ./dfuse.py ../src/build/gnuk.hex
+
+Then, reset the board.
+
+
+How to protect flash ROM
+========================
+
+Invoke your OpenOCD and type:
+
+  $ telnet localhost 4444
+  > reset halt
+  > stm32f1x lock 0
+  > reset
+  > shutdown
+
+After power-off / power-on sequence, the contents of flash ROM cannot
+be accessible from JTAG debugger.
+
+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.
+
+
+How to configure
+================
+
+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.
+
+If scdaemon is running, please kill it, or you will get "Smartcard
+Exception" by "Sharing violation".
+
+  $ gpg-connect-agent "SCD KILLSCD" "SCD BYE" /bye
+
+In case of PyUSB tool, you need to stop pcscd.
+
+  # /etc/init.d/pcscd stop
+
+
+(2) [Optional] Write fixed serial number
+
+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
+  Writing serial number
+  ...
+
+(3) [Optional] Write card holder certificate
+
+If you have card holder certificate binary file, you can do:
+
+  $ ../tool/gnuk_put_binary.py ../../<YOUR-CERTIFICATE>.bin
+  ../../<YOUR-CERTIFICATE>.bin: <LENGTH-OF-YOUR-CERTIFICATE>
+  Updating card holder certificate
+  ...
+
+
+How to run
+==========
+
+Debug enabled
+-------------
+
+If you compiled with --enable-debug option, Gnuk has two interfaces
+(one is CCID/ICCD device and another is virtual COM port).  Open
+virtual COM port by:
+
+  $ cu -l /dev/ttyACM0
+
+and you will see debug output of Gnuk.
+
+
+Testing Gnuk
+------------
+
+Type following command to see Gnuk runs:
+
+  $ gpg --card-status
+
+
+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.  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.
+
+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.
+
+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
+============
+
+We can use GDB.
+
+  $ arm-none-eabi-gdb gnuk.elf
+
+
+Inside GDB, we can connect OpenOCD by:
+
+  (gdb) target remote localhost:3333
+
+
+You can see the output of PCSCD:
+
+  # /etc/init.d/pcscd stop
+  # LIBCCID_ifdLogLevel=7 /usr/sbin/pcscd --debug --foreground
+
+
+You can observe the traffic of USB using "usbmon".  See the file:
+linux/Documentation/usb/usbmon.txt
+
+
+Firmware update
+===============
+
+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
+
+It's also available at: www.gniibe.org
+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
+
+We have migrated from ChibiOS/RT to Chopstx.  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
+======================
+
+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).
+
+
+Foot note
+==========
 
-$ telnet localhost 4444
-> reset halt
-> flash write_image erase gnuk.elf
-> reset
-> exit
-$ 
+* NUK(R) is a registered trademark owend by MAPA GmbH, Germany.
+--