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