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