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