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