add FST-01 description
[gnuk/gnuk.git] / README
1 Gnuk - software for GnuPG USB Token
2
3                                                            Version 0.15
4                                                              2011-11-XX
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 am with a USB
23 Token by "Gnuk", always, everywhere.
24
25
26 FAQ
27 ===
28
29 Q0: How Gnuk USB Token is superior than other solutions (OpenPGP
30     card 2.0, GPF Crypto Stick, etc.) ?
31     http://www.g10code.de/p-card.html
32     http://www.privacyfoundation.de/crypto_stick/
33 A0: IMRHO, not quite.  There is no ready-to-use out-of-box product.
34     (It is welcome for me that some vendor will manufacture Gnuk USB
35      Token.  Even I can help design of hardware, if needed.)
36     Good points are:
37     * If you have skill of electronics and like DIY, you can build
38       Gnuk Token cheaper (see Q8-A8).
39     * You can study Gnuk to modify and to enhance.  For example, you
40       can implement your own authentication method with some sensor
41       such as acceleration sensor.
42     * It is "of Free Software"; Gnuk is distributed under GPLv3+,
43             "by Free Software"; Gnuk development requires only Free Software
44                                 (GNU Toolchain, Python, etc.), 
45             "for Free Software"; Gnuk supports GnuPG.
46
47 Q1: What kind of key algorithm is supported?
48 A1: Gnuk only supports 2048-bit RSA.
49
50 Q2: How long does it take for digital signing?
51 A2: It takes a second and a half or so. 
52
53 Q3: What's your recommendation for target board?
54 A3: Orthodox choice is Olimex STM32-H103.
55     If you have skill of electronics and like DIY, STM32 part of STM8S
56     Discovery Kit might be the best choice.
57     Currently FST-01 (Flying Stone Tiny 01) is under development,
58     it will be the best choice, hopefully.
59
60 Q4: What's version of GnuPG are you using?
61 A4: In Debian GNU/Linux system, I use gnupg 1.4.11-3 and gnupg-agent
62     2.0.14-2 (in sid).  With older versions, you can only sign with SHA1.
63     See: http://www.fsij.org/gnuk/gnupg2-fixes-needed
64
65 Q5: What's version of pcscd and libccid are you using?
66 A5: In Debian GNU/Linux system, I use pcscd 1.5.5-4 and libccid 1.3.11-2,
67     which is in squeeze.  Note that you need to edit /etc/libccid_Info.plist
68     when using libccid (< 1.4.1).
69
70 Q6: What kinds of hardware is required for development?
71 A6: You need a target board plus a JTAG debugger.  If you just want to
72     test Gnuk for target boards with DfuSe, JTAG debugger is not
73     the requirement.  Note that for real use, you need JTAG debugger
74     to enable flash ROM protection.
75
76 Q7: How much does it cost?
77 A7: Olimex STM32-H103 plus ARM-USB-TINY-H cost 70 Euro or so.
78
79 Q8: How much does it cost for DIY version?
80 A8: STM8S Discovery Kit costs 750 JPY (< $10 USD) only.  You can build
81     your own JTAG debugger using FTDI2232 module (1450 JPY), see:
82     http://www.fsij.org/gnuk/jtag_dongle_ftdi2232
83
84 Q9: I got an error like "gpg: selecting openpgp failed: ec=6.108", what's up?
85 A9: GnuPG's SCDaemon has problems for handling insertion/removal of
86     card/reader (problems are fixed in trunk).  When your newly
87     inserted token is not found by GnuPG, try killing scdaemon and let
88     it to be invoked again.  I do:
89       $ killall -9 scdaemon
90     and confirm scdaemon doesn't exist, then,
91       $ gpg-connect-agent learn /bye
92
93
94 Release notes
95 =============
96
97 This is sixteenth release of Gnuk.  While it works well for specific
98 usages and it is considered stable, it is still somewhat experimental.
99
100 Tested features are:
101
102         * Personalization of the card
103           * Changing Login name, URL, Name, Sex, Language, etc.
104         * Password handling (PW1, RC, PW3)
105         * Key import for three types:
106           * key for digital signing
107           * key for decryption
108           * key for authentication
109         * PSO: Digital Signature
110         * PSO: Decipher
111         * INTERNAL AUTHENTICATE
112         * Changing value of password status bytes (0x00C4): forcesig
113         * Verify with pin pad
114         * Modify with pin pad
115
116 It is known not-working well:
117
118         * For some version of kernel and libccid, --enable-debug can't
119           work well.  Please disable DEBUG option if it doesn't work well.
120
121         * Card holder certificate
122           It is implemented in Gnuk side.  But its large size matters
123           (> 1KB).  Some versions of GnuPG cannot handle a data object
124           of large size with PC/SC backend.  Specifically,
125           handle_transmit function in pcsc-wrapper.c uses the buffer
126           of size 1024-byte.
127
128 Not supported feature(s):
129
130         * Overriding key import.  You need to remove all keys first.
131         * Key generation on device side
132
133
134 Targets
135 =======
136
137 We use Olimex STM32-H103 board and Flying Stone Tiny 01 (FST-01).  We
138 also use STM32 part of STM8S Discovery Kit.
139
140 With DfuSe support, CQ STARM, STBee, and STBee Mini are also our
141 targets.  But those targets with DfuSe are basically not for normal
142 use but for experiments, because it would be impossible for DfuSe to
143 disable read from flash.  For real use, please consider killing DfuSe
144 and enable read protection using JTAG debugger.
145
146 I think that it could run on Olimex STM32-P103, or other boards with
147 STM32F103.  Besides, we are porting it to STM32 Primer 2.
148
149 For PIN-pad support, I connect a consumer IR receive module to STBee
150 Mini and STM8S Discovery Kit, and use controller for TV.  PIN
151 verification is supported by this configuration.  Yes, it is not
152 secure at all, since it is very easy to monitor IR output of the
153 controllers.  It is just an experiment.  Note that hardware needed for
154 this experiment is only a consumer IR receive module which is as cheap
155 as 50 JPY.
156
157 Another PIN-pad support is connecting rotary encoder, push switch and
158 7-segment LED display.  Both of PIN verification and PIN modification
159 are supported for this circuit extension.
160
161
162 Souce code
163 ==========
164
165 Gnuk source code is under src/ directory.
166
167
168 License
169 =======
170
171 It is distributed under GNU General Public Licence version 3 or later
172 (GPLv3+).  Please see src/COPYING.
173
174 Please note that it is distributed with external source code too.
175 Please read relevant licenses for external source code, too.
176
177 The author(s) of Gnuk expect users of Gnuk will be able to access the
178 source code of Gnuk, so that users can study the code and can modify
179 if needed.  This doesn't mean person who has a USB Token by Gnuk
180 should be able to acess everything on the Token, regardless of its
181 protections.  Private keys, and other information should be protected
182 properly.
183
184
185 External source code
186 ====================
187
188 Gnuk is distributed with external source code.
189
190 * ChibiOS_2.0.8/  -- ChibiOS/RT 2.0.8
191
192   Taken from http://chibios.sourceforge.net/
193   Note that CRLF is converted to LF in this repository.
194   We use ChibiOS/RT as the kernel for Gnuk.
195
196 * polarssl-0.14.0/  -- PolarSSL 0.14.0
197
198   Taken from http://polarssl.org/
199   We use PolarSSL for RSA computation, AES encryption/decryption
200   and SHA-1 computation.
201
202   The file include/polarssl/bn_mul.h is heavily modified for ARM
203   Cortex-M3.
204
205 * STM32_USB-FS-Device_Driver/ -- a part of USB-FS-Device_Lib
206 * Virtual_COM_Port/ -- a part of USB-FS-Device_Lib
207
208   STM32F10x USB Full Speed Device Library (USB-FS-Device_Lib)
209   is a STM32F10x library for USB functionality.
210
211   I took Libraries/STM32_USB-FS-Device_Driver and 
212   Project/Virtual_COM_Port in STM32_USB-FS-Device_Lib distribution.
213   See http://www.st.com/ for detail.
214
215
216 Host Requirements
217 =================
218
219 For GNU/Linux, libccid version >= 1.3.11 is required.
220 libccid version == 1.3.9 is known not working well by the issue [r4235].
221
222 I think that it should not be requirment but the kernel version of my use is:
223 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
224
225 Linux 2.6.30 is known *NOT* working well with DEBUG option.
226 Linux 2.6.24 is known working well with DEBUG option.
227
228
229 How to compile
230 ==============
231
232 You need GNU toolchain and newlib for 'arm-none-eabi' target.
233
234 See http://github.com/esden/summon-arm-toolchain/ (which includes fix
235 of binutils-2.21.1) for preparation of GNU Toolchain for
236 'arm-none-eabi' target.
237
238 # Note that we need to link correct C library (for string functions).
239 # For this purpose, Makefile.in contains following line:
240
241 #       MCFLAGS= -mcpu=$(MCU) -mfix-cortex-m3-ldrd
242
243 # This should not be needed (as -mcpu=cortex-m3 means
244 # -mfix-cortex-m3-ldrd), but in practice it is needed for 
245 # the configuration of patch-gcc-config-arm-t-arm-elf.diff in
246 # summon-arm-toolchain.
247
248 # In ChibiOS_2.0.8/os/ports/GCC/ARM/rules.mk, it specifies
249 # -mno-thumb-interwork option.  This means that you should not
250 # link C library which contains ARM (not Thumb) code.
251
252
253 Change directory to `src':
254
255   $ cd gnuk-VERSION/src
256
257 Then, run `configure':
258
259   $ ./configure
260
261 Type:
262
263   $ make
264
265 Then, we will have "gnuk.elf".
266
267
268 How to install
269 ==============
270
271 Olimex STM32-H103 board
272 -----------------------
273
274 If you are using Olimex JTAG-Tiny, type following to invoke OpenOCD:
275
276   $ openocd -f interface/olimex-jtag-tiny.cfg -f board/olimex_stm32_h103.cfg
277
278 Then, with another terminal, type following to write "gnuk.elf" to Flash ROM:
279
280   $ telnet localhost 4444
281   > reset halt
282   > flash write_image erase gnuk.elf
283   > reset
284   > exit
285   $ 
286
287
288 Flying Stone Tiny 01
289 --------------------
290
291 If you are using Flying Stone Tiny 01, you need a SWD writer.  I am
292 using revision 946 of Simon Qian's Versaloon.
293
294     svn checkout -r 946 http://vsprog.googlecode.com/svn/trunk/
295
296 For OpenOCD, we need unofficial patch.
297
298 See the article of Versaloon Forum:
299
300     http://www.versaloon.com/bbs/viewtopic.php?p=16179
301
302
303 Type following to invoke OpenOCD:
304
305   $ openocd -f interface/vsllink.cfg -c "transport select swd" -c "swd_mode 2" -f target/stm32f1x.cfg
306
307 Then, with another terminal, type following to write "gnuk.elf" to Flash ROM:
308
309   $ telnet localhost 4444
310   > reset halt
311   > flash write_image erase gnuk.elf
312   > reset
313   > exit
314   $ 
315
316
317
318 STM8S Discovery Kit
319 -------------------
320
321 If you are using FTDI-2232D module and the connection is standard, type:
322
323   $ openocd -f interface/openocd-usb.cfg -f target/stm32.cfg
324
325 Initially, the flash ROM of the chip is protected.  you need to do:
326
327   $ telnet localhost 4444
328   > reset halt
329   > stm32x unlock 0
330   > reset
331   > shutdown
332   $ 
333
334 and re-connect the board.  Note that power-off / power-on sequence is
335 required to reset flash ROM.
336
337 Then, invoke OpenOCD again and telnet to connect OpenCD and write
338 image as above example of Olimex STM32-H103.
339
340
341 CQ STARM
342 --------
343
344 Put jumper for J6 to enable DfuSe.  Connecting the board, and type:
345
346   # cd ../tool
347   # ./dfuse.py ../src/gnuk.hex
348
349 Then, remove the jumper and reset the board.
350
351
352 STBee and STBee Mini
353 --------------------
354
355 Reset the board with "USER" switch pushed.  Type following to write
356 to flash:
357
358   # cd ../tool
359   # ./dfuse.py ../src/gnuk.hex
360
361 Then, reset the board.
362
363
364 How to protect flash ROM
365 ========================
366
367 Invoke your OpenOCD and type:
368
369   $ telnet localhost 4444
370   > reset halt
371   > stm32x lock 0
372   > reset
373   > shutdown
374
375 After power-off / power-on sequence, the contents of flash ROM cannot
376 be accessible from JTAG debugger.
377
378 Note that it would be still possible for some implementation of DfuSe
379 to access the contents.  If you want to protect, killing DfuSe and
380 accessing by JTAG debugger is recommended.
381
382
383 How to configure
384 ================
385
386 You need python and pyscard (python-pyscard package in Debian) or
387 PyUSB (python-usb package in Debian).
388
389 (1) [pyscard] Stop scdaemon
390     [PyUSB] Stop the pcsc daemon.
391
392 If scdaemon is running, please kill it, or you will get "Smartcard
393 Exception" by "Sharing violation".
394
395   $ killall -9 scdaemon
396
397 In case of PyUSB tool, you need to stop pcscd.
398
399   # /etc/init.d/pcscd stop
400
401
402 (2) [Optional] Write fixed serial number
403
404 If you use fixed serial number in the file 'GNUK_SERIAL_NUMBER', you can do:
405
406   $ EMAIL=<YOUR-EMAIL-ADDRESS> ../tool/gnuk_put_binary.py -s ../GNUK_SERIAL_NUMBER
407   Writing serial number
408   ...
409
410 (3) [Optional] Write card holder certificate
411
412 If you have card holder certificate binary file, you can do:
413
414   $ ../tool/gnuk_put_binary.py ../../<YOUR-CERTIFICATE>.bin
415   ../../<YOUR-CERTIFICATE>.bin: <LENGTH-OF-YOUR-CERTIFICATE>
416   Updating card holder certificate
417   ...
418
419
420 How to run
421 ==========
422
423 Debug enabled
424 -------------
425
426 If you compiled with --enable-debug option, Gnuk has two interfaces
427 (one is CCID/ICCD device and another is virtual COM port).  Open
428 virtual COM port by:
429
430   $ cu -l /dev/ttyACM0
431
432 and you will see debug output of Gnuk.
433
434
435 Libccid fix needed
436 ------------------
437
438 For libccid (< 1.4.1), we need following change:
439
440 --- /etc/libccid_Info.plist.dpkg-dist   2009-07-29 06:50:20.000000000 +0900
441 +++ /etc/libccid_Info.plist     2010-09-05 09:09:49.000000000 +0900
442 @@ -104,6 +104,7 @@
443  
444         <key>ifdVendorID</key>
445         <array>
446 +               <string>0x234B</string>
447                 <string>0x08E6</string>
448                 <string>0x08E6</string>
449                 <string>0x08E6</string>
450 @@ -237,6 +238,7 @@
451  
452         <key>ifdProductID</key>
453         <array>
454 +               <string>0x0000</string>
455                 <string>0x2202</string>
456                 <string>0x3437</string>
457                 <string>0x3438</string>
458 @@ -370,6 +372,7 @@
459  
460         <key>ifdFriendlyName</key>
461         <array>
462 +               <string>FSIJ USB Token</string>
463                 <string>Gemplus Gem e-Seal Pro</string>
464                 <string>Gemplus GemPC Twin</string>
465                 <string>Gemplus GemPC Key</string>
466 ------------------
467
468 This entry has been added into libccid 1.4.1 already ([r5425]).
469
470
471 Testing Gnuk
472 ------------
473
474 Try following to see Gnuk runs:
475
476   $ gpg --card-status
477
478
479 Personalize the Token and import keys
480 -------------------------------------
481
482 You can personalize the token, putting your information like: Name,
483 Login name, Sex, Languages, URL, etc., and password.  To do so, GnuPG
484 command is:
485
486   $ gpg --card-edit
487
488 Note that the factory setting of user password is "123456" and admin
489 password is "12345678" as the specification.
490
491 No, Gnuk doesn't support key generation.  You need to create your
492 keys on your computer, and import them to Gnuk Token.  After you create
493 your keys (they must be 2048-bit RSA), you can import them.
494
495 For detail, please see doc/DEMO and doc/DEMO-2.
496
497 Note that it make sense to preserve your keys on your computer so that
498 you can import the keys (again) to (possibly another) Gnuk Token.  In
499 this case, you can use GnuPG's option to specify the home directory by
500 --homedir.
501
502 After creating keys by:
503
504   $ gpg --gen-key
505   ...
506
507 Copy directory which contains your secret keys to new directory named
508 <gpgdir-with-your-secret-keys>:
509
510   $ cp -pa $HOME/.gnupg <gpgdir-with-your-secret-keys>
511
512 Then, import keys by:
513
514   $ gpg --edit-key <YOUR-KEYID>
515
516 While your $HOME/.gnupg now doesn't have your secret keys after
517 import, <gpgdir-with-your-secret-keys> still has them.  You can again
518 import them by:
519
520   $ gpg --homedir=<gpgdir-with-your-secret-keys> --edit-key <YOUR-KEYID>
521
522 Note that you *should not* save changes this time to preserve keys
523 on your computer.  The session goes like this:
524
525   gpg> quit
526   Save changes? (y/N) n
527   Quit without saving? (y/N) y
528
529
530
531 How to debug
532 ============
533
534 We can use GDB.
535
536   $ arm-none-eabi-gdb gnuk.elf
537
538
539 Inside GDB, we can connect OpenOCD by:
540
541   (gdb) target remote localhost:3333
542
543
544 You can see the output of PCSCD:
545
546   # /etc/init.d/pcscd stop
547   # LIBCCID_ifdLogLevel=7 /usr/sbin/pcscd --debug --foreground
548
549
550 You can observe the traffic of USB using "usbmon".  See the file:
551 linux/Documentation/usb/usbmon.txt
552
553
554 Read-only Git Repository
555 ========================
556
557 You can browse at http://www.gniibe.org/gitweb?p=gnuk.git;a=summary
558
559 You can get it by:
560
561   $ git clone git://www.gniibe.org/gnuk.git/
562
563 or
564
565   $ git clone http://www.gniibe.org/git/gnuk.git/
566
567
568
569 Information on the Web
570 ======================
571
572 Please visit: http://www.fsij.org/gnuk/
573
574
575 Your Contributions
576 ==================
577
578 FSIJ welcomes your contributions.  Please assign your copyright
579 to FSIJ (if possible).
580
581
582 Foot note
583 ==========
584 * NUK(R) is a registered trademark owend by MAPA GmbH, Germany.
585 --