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