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