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