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