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