README

   1 Gnuk - software for GPG USB Token
   2
   3                                                             Version 0.9
   4                                                              2011-02-01
   5                                                            Niibe Yutaka
   6                                       Free Software Initiative of Japan
   7
   8 What's Gnuk?
   9 ============
  10
  11 Gnuk is software implementation of a USB token for GNU Privacy Guard.
  12 Gnuk supports OpenPGP card protocol version 2, and it runs on STM32
  13 processor.
  14
  15 I wish that Gnuk will be a developer's soother who uses GnuPG.  I have
  16 been nervous of storing secret key(s) on usual secondary storage.
  17 While I want to work at different places, but it is not the choice for
  18 me to bring a card reader all the time.  With Gnuk, this issue will be
  19 solved by a USB token which is small enough.
  20
  21 Please look at the graphics of "gnuk.svg" for the software name.  My
  22 son used to be with his NUK(R), always, everywhere.  I will be with a
  23 USB Token by Gnuk everywhere.
  24
  25
  26 Release notes
  27 =============
  28
  29 This is tenth release of Gnuk.  While it works well for specific
  30 usages, it is still experimental.
  31
  32 Tested features are:
  33
  34         * Personalization of the card
  35
  36           * Changing Login name, URL, Name, Sex, Language, etc.
  37
  38         * Password handling (PW1, RC, PW3)
  39
  40         * Key import for three types:
  41
  42           * key for digital signing
  43
  44           * key for decryption
  45
  46           * key for authentication
  47
  48         * PSO: Digital Signature
  49
  50         * PSO: Decipher
  51
  52         * INTERNAL AUTHENTICATE
  53
  54         * Changing value of password status bytes (0x00C4)
  55
  56         * Verify with pin pad
  57
  58         * Modify with pin pad
  59
  60 It is known not-working well:
  61
  62         * For some version of kernel and libccid, --enable-debug can't
  63           work well.  Please disable DEBUG option if it doesn't work well.
  64
  65         * Card holder certificate
  66           It is implemented in Gnuk side.  But its size matters (>
  67           1KB).  GnuPG cannot handle a data object of large size with
  68           PC/SC backend.  Specifically, handle_transmit function in
  69           pcsc-wrapper.c uses the buffer of size 1024-byte.
  70
  71 Not supported feature(s):
  72
  73         * Overriding key import.  You need to remove all keys first.
  74
  75
  76 Targets
  77 =======
  78
  79 We use Olimex STM32-H103 board.  We also use STM32 part of STM8S
  80 Discovery Kit.
  81
  82 With DfuSe support, CQ STARM, STBee, and STBee Mini are also our
  83 targets.  But those targets with DfuSe are basically not for normal
  84 use but for experiments, because it would be impossible for DfuSe to
  85 disable read from flash.  For real use, please consider killing DfuSe
  86 and enable read protect using JTAG debugger.
  87
  88 I think that it could run on Olimex STM32-P103, or other boards with
  89 STM32F103.  Besides, we are porting it to STM32 Primer 2.
  90
  91 For PIN-pad support, I connect a consumer IR receive module to STBee
  92 Mini and STM8S Discovery Kit, and use controller for TV.  PIN
  93 verification is supported by this configuration.  Yes, it is not
  94 secure at all, since it is very easy to monitor IR output of the
  95 controllers.  It is just an experiment.  Note that hardware needed for
  96 this experiment is only a consumer IR receive module which is as cheap
  97 as 50 JPY.
  98
  99 Another PIN-pad support is connecting rotary encoder, push switch and
 100 7-segment LED display.  Both of PIN verification and PIN modification
 101 are supported for this circuit extension.
 102
 103
 104 Souce code
 105 ==========
 106
 107 Gnuk source code is under src/ directory.
 108
 109
 110 License
 111 =======
 112
 113 It is distributed under GNU General Public Licence version 3 or later
 114 (GPLv3+).  Please see src/COPYING.
 115
 116 Please note that it is distributed with external source code too.
 117 Please read relevant licenses for external source code, too.
 118
 119 The author(s) of Gnuk expect users of Gnuk will be able to access the
 120 source code of Gnuk, so that users can study the code and can modify
 121 if needed.  This doesn't mean person who has a USB Token by Gnuk
 122 should be able to acess everything on the Token, regardless of its
 123 protections.  Private keys, random bytes, and other information should
 124 be protected properly.
 125
 126
 127 External source code
 128 ====================
 129
 130 Gnuk is distributed with external source code.
 131
 132 * ChibiOS_2.0.8/  -- ChibiOS/RT 2.0.8
 133
 134   Taken from http://chibios.sourceforge.net/
 135   Note that CRLF is converted to LF in this repository.
 136   We use ChibiOS/RT as the kernel for Gnuk.
 137
 138 * polarssl-0.14.0/  -- PolarSSL 0.14.0
 139
 140   Taken from http://polarssl.org/
 141   We use PolarSSL for RSA computation, AES encryption/decryption
 142   and SHA-1 computation.
 143
 144 * STM32_USB-FS-Device_Driver/ -- a part of USB-FS-Device_Lib
 145 * Virtual_COM_Port/ -- a part of USB-FS-Device_Lib
 146
 147   STM32F10x USB Full Speed Device Library (USB-FS-Device_Lib)
 148   is a STM32F10x library for USB functionality.
 149
 150   I took Libraries/STM32_USB-FS-Device_Driver and
 151   Project/Virtual_COM_Port in STM32_USB-FS-Device_Lib distribution.
 152   See http://www.st.com/ for detail.
 153
 154
 155 Host Requirements
 156 =================
 157
 158 For GNU/Linux, libccid version >= 1.3.11 is required.
 159 libccid version == 1.3.9 is known not working well by the issue [r4235].
 160
 161 I think that it should not be requirment but the kernel version of my use is:
 162 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
 163
 164 Linux 2.6.30 is known *NOT* working well with DEBUG option.
 165 Linux 2.6.24 is known working well with DEBUG option.
 166
 167
 168 How to compile
 169 ==============
 170
 171 You need GNU toolchain and newlib for 'arm-none-eabi' target.
 172
 173 See http://github.com/esden/summon-arm-toolchain/ for preparation of
 174 GNU Toolchain for 'arm-none-eabi' target.
 175
 176 Change directory to `src':
 177
 178   $ cd gnuk-VERSION/src
 179
 180 Then, run `configure':
 181
 182   $ ./configure
 183
 184 Type:
 185
 186   $ make
 187
 188 In the make process, it takes time for the command of
 189
 190    dd if=/dev/random bs=1 of=random_bits count=1024
 191
 192 Don't just wait, but do some other work on your PC.
 193 /dev/random needs entropy to finish.
 194
 195 Then, we will have "gnuk.elf".
 196
 197
 198 How to run
 199 ==========
 200
 201 Olimex STM32-H103 board
 202 -----------------------
 203
 204 If you are using Olimex JTAG-Tiny, type following to invoke OpenOCD:
 205
 206   $ openocd -f interface/olimex-jtag-tiny.cfg -f board/olimex_stm32_h103.cfg
 207
 208 Then, with another terminal, type following to write "gnuk.elf" to Flash ROM:
 209
 210   $ telnet localhost 4444
 211   > reset halt
 212   > flash write_image erase gnuk.elf
 213   > reset
 214   > exit
 215   $
 216
 217
 218 STM8S Discovery Kit
 219 -------------------
 220
 221 If you are using FTDI-2232D module and the connection is standard, type:
 222
 223   $ openocd -f interface/openocd-usb.cfg -f target/stm32.cfg
 224
 225 Then, invoke telnet to connect OpenCD and write image as above example
 226 of Olimex STM32-H103.
 227
 228
 229 CQ STARM
 230 --------
 231
 232 Put jumper for J6 to enable DfuSe.  Connecting the board, and type:
 233
 234   # cd ../tool
 235   # ./dfuse.py ../src/gnuk.hex
 236
 237 Then, remove the jumper and reset the board.
 238
 239
 240 STBee and STBee Mini
 241 --------------------
 242
 243 Reset the board with "USER" switch pushed.  Type following to write
 244 to flash:
 245
 246   # cd ../tool
 247   # ./dfuse.py ../src/gnuk.hex
 248
 249 Then, reset the board.
 250
 251
 252 Debug enabled
 253 -------------
 254
 255 If you compiled with --enable-debug option, Gnuk has two interfaces
 256 (one is CCID/ICCD device and another is virtual COM port).  Open
 257 virtual COM port by:
 258
 259   $ cu -l /dev/ttyACM0
 260
 261 and you will see debug output of Gnuk.
 262
 263
 264 Libccid fix needed
 265 ------------------
 266
 267 For libccid (< 1.4.1), we need following change:
 268
 269 --- /etc/libccid_Info.plist.dpkg-dist   2009-07-29 06:50:20.000000000 +0900
 270 +++ /etc/libccid_Info.plist     2010-09-05 09:09:49.000000000 +0900
 271 @@ -104,6 +104,7 @@
 272
 273         <key>ifdVendorID</key>
 274         <array>
 275 +               <string>0x234B</string>
 276                 <string>0x08E6</string>
 277                 <string>0x08E6</string>
 278                 <string>0x08E6</string>
 279 @@ -237,6 +238,7 @@
 280
 281         <key>ifdProductID</key>
 282         <array>
 283 +               <string>0x0000</string>
 284                 <string>0x2202</string>
 285                 <string>0x3437</string>
 286                 <string>0x3438</string>
 287 @@ -370,6 +372,7 @@
 288
 289         <key>ifdFriendlyName</key>
 290         <array>
 291 +               <string>FSIJ USB Token</string>
 292                 <string>Gemplus Gem e-Seal Pro</string>
 293                 <string>Gemplus GemPC Twin</string>
 294                 <string>Gemplus GemPC Key</string>
 295 ------------------
 296
 297 This entry has been added into libccid 1.4.1 already ([r5425]).
 298
 299
 300 Testing Gnuk
 301 ------------
 302
 303 Try following to see Gnuk runs:
 304
 305   $ gpg --card-status
 306
 307
 308 For more, see doc/DEMO.
 309
 310
 311
 312 How to debug
 313 ============
 314
 315 We can use GDB.
 316
 317   $ arm-none-eabi-gdb gnuk.elf
 318
 319
 320 Inside GDB, we can connect OpenOCD by:
 321
 322   (gdb) target remote localhost:3333
 323
 324
 325 You can see the output of PCSCD:
 326
 327   # /etc/init.d/pcscd stop
 328   # LIBCCID_ifdLogLevel=7 /usr/sbin/pcscd --debug --foreground
 329
 330
 331 You can observe the traffic of USB using "usbmon".  See the file:
 332 linux/Documentation/usb/usbmon.txt
 333
 334
 335 Read-only Git Repository
 336 ========================
 337
 338 You can get it by:
 339
 340   $ git clone http://www.gniibe.org/git/gnuk.git/
 341
 342
 343 Information on the Web
 344 ======================
 345
 346 Please see: http://www.fsij.org/gnuk/
 347
 348
 349 Your Contributions
 350 ==================
 351
 352 FSIJ welcomes your contributions.  Please assign your copyright
 353 to FSIJ (if possible).
 354
 355
 356 Foot note
 357 ==========
 358 * NUK(R) is a registered trademark owend by MAPA GmbH, Germany.
 359 --