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