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