add NEWS, README
[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 OpenOCD 0.6.1 now supports ST-Link/V2.  We can use it:
417
418   $ openocd -f interface/stlink-v2.cfg -f target/stm32f1x_stlink.cfg
419
420 But it doesn't support option bytes handling yet.
421
422
423 STM8S Discovery Kit
424 -------------------
425
426 If you are using FTDI-2232D module and the connection is standard, type:
427
428   $ openocd -f interface/openocd-usb.cfg -f target/stm32.cfg
429
430 Initially, the flash ROM of the chip is protected.  you need to do:
431
432   $ telnet localhost 4444
433   > reset halt
434   > stm32x unlock 0
435   > reset
436   > shutdown
437   $ 
438
439 and re-connect the board.  Note that power-off / power-on sequence is
440 required to reset flash ROM.
441
442 Then, invoke OpenOCD again and telnet to connect OpenCD and write
443 image as above example of Olimex STM32-H103.
444
445
446 CQ STARM
447 --------
448
449 Put jumper for J6 to enable DfuSe.  Connecting the board, and type:
450
451   # cd ../tool
452   # ./dfuse.py ../src/gnuk.hex
453
454 Then, remove the jumper and reset the board.
455
456
457 STBee and STBee Mini
458 --------------------
459
460 Reset the board with "USER" switch pushed.  Type following to write
461 to flash:
462
463   # cd ../tool
464   # ./dfuse.py ../src/gnuk.hex
465
466 Then, reset the board.
467
468
469 How to protect flash ROM
470 ========================
471
472 Invoke your OpenOCD and type:
473
474   $ telnet localhost 4444
475   > reset halt
476   > stm32x lock 0
477   > reset
478   > shutdown
479
480 After power-off / power-on sequence, the contents of flash ROM cannot
481 be accessible from JTAG debugger.
482
483 Note that it would be still possible for some implementation of DfuSe
484 to access the contents.  If you want to protect, killing DfuSe and
485 accessing by JTAG debugger is recommended.
486
487
488 How to configure
489 ================
490
491 You need python and pyscard (python-pyscard package in Debian) or
492 PyUSB (python-usb package in Debian).
493
494 (1) [pyscard] Stop scdaemon
495     [PyUSB] Stop the pcsc daemon.
496
497 If scdaemon is running, please kill it, or you will get "Smartcard
498 Exception" by "Sharing violation".
499
500   $ gpg-connect-agent "SCD KILLSCD" "SCD BYE" /bye
501
502 In case of PyUSB tool, you need to stop pcscd.
503
504   # /etc/init.d/pcscd stop
505
506
507 (2) [Optional] Write fixed serial number
508
509 If you use fixed serial number in the file 'GNUK_SERIAL_NUMBER', you can do:
510
511   $ EMAIL=<YOUR-EMAIL-ADDRESS> ../tool/gnuk_put_binary.py -s ../GNUK_SERIAL_NUMBER
512   Writing serial number
513   ...
514
515 (3) [Optional] Write card holder certificate
516
517 If you have card holder certificate binary file, you can do:
518
519   $ ../tool/gnuk_put_binary.py ../../<YOUR-CERTIFICATE>.bin
520   ../../<YOUR-CERTIFICATE>.bin: <LENGTH-OF-YOUR-CERTIFICATE>
521   Updating card holder certificate
522   ...
523
524
525 How to run
526 ==========
527
528 Debug enabled
529 -------------
530
531 If you compiled with --enable-debug option, Gnuk has two interfaces
532 (one is CCID/ICCD device and another is virtual COM port).  Open
533 virtual COM port by:
534
535   $ cu -l /dev/ttyACM0
536
537 and you will see debug output of Gnuk.
538
539
540 Libccid fix needed
541 ------------------
542
543 For libccid (< 1.4.1), we need following change:
544
545 --- /etc/libccid_Info.plist.dpkg-dist   2009-07-29 06:50:20.000000000 +0900
546 +++ /etc/libccid_Info.plist     2010-09-05 09:09:49.000000000 +0900
547 @@ -104,6 +104,7 @@
548  
549         <key>ifdVendorID</key>
550         <array>
551 +               <string>0x234B</string>
552                 <string>0x08E6</string>
553                 <string>0x08E6</string>
554                 <string>0x08E6</string>
555 @@ -237,6 +238,7 @@
556  
557         <key>ifdProductID</key>
558         <array>
559 +               <string>0x0000</string>
560                 <string>0x2202</string>
561                 <string>0x3437</string>
562                 <string>0x3438</string>
563 @@ -370,6 +372,7 @@
564  
565         <key>ifdFriendlyName</key>
566         <array>
567 +               <string>FSIJ USB Token</string>
568                 <string>Gemplus Gem e-Seal Pro</string>
569                 <string>Gemplus GemPC Twin</string>
570                 <string>Gemplus GemPC Key</string>
571 ------------------
572
573 This entry has been added into libccid 1.4.1 already ([r5425]).
574
575
576 Testing Gnuk
577 ------------
578
579 Type following command to see Gnuk runs:
580
581   $ gpg --card-status
582
583
584 Besides, there is a functinality test under test/ directory.  See
585 test/README.
586
587
588 Personalize the Token and import keys
589 -------------------------------------
590
591 You can personalize the token, putting your information like: Name,
592 Login name, Sex, Languages, URL, etc., and password.  To do so, GnuPG
593 command is:
594
595   $ gpg --card-edit
596
597 Note that the factory setting of user password is "123456" and admin
598 password is "12345678" as the specification.
599
600 It is recommended to create your keys on your computer, and import
601 them to Gnuk Token.  After you create your keys (they must be 2048-bit
602 RSA), you can import them.
603
604 Gnuk supports key generation, but this feature is young and should be
605 considered experimental.
606
607 For detail, please see doc/note/DEMO and doc/note/DEMO-2.
608
609 Note that it make sense to preserve your keys on your computer so that
610 you can import the keys (again) to (possibly another) Gnuk Token.  In
611 this case, you can use GnuPG's option to specify the home directory by
612 --homedir.
613
614 After creating keys on your computer by:
615
616   $ gpg --gen-key
617   ...
618
619 Copy directory which contains your secret keys to new directory named
620 <gpgdir-with-your-secret-keys>:
621
622   $ cp -pa $HOME/.gnupg <gpgdir-with-your-secret-keys>
623
624 Then, import keys by:
625
626   $ gpg --edit-key <YOUR-KEYID>
627
628 While your $HOME/.gnupg now doesn't have your secret keys after
629 import, <gpgdir-with-your-secret-keys> still has them.  You can again
630 import them by:
631
632   $ gpg --homedir=<gpgdir-with-your-secret-keys> --edit-key <YOUR-KEYID>
633
634 Note that you *should not* save changes this time to preserve keys
635 on your computer.  The session goes like this:
636
637   gpg> quit
638   Save changes? (y/N) n
639   Quit without saving? (y/N) y
640
641
642
643 How to debug
644 ============
645
646 We can use GDB.
647
648   $ arm-none-eabi-gdb gnuk.elf
649
650
651 Inside GDB, we can connect OpenOCD by:
652
653   (gdb) target remote localhost:3333
654
655
656 You can see the output of PCSCD:
657
658   # /etc/init.d/pcscd stop
659   # LIBCCID_ifdLogLevel=7 /usr/sbin/pcscd --debug --foreground
660
661
662 You can observe the traffic of USB using "usbmon".  See the file:
663 linux/Documentation/usb/usbmon.txt
664
665
666 Firmware update
667 ===============
668
669 See doc/note/firmware-update.
670
671
672 Git Repositories
673 ================
674
675 You can browse at: http://www.gniibe.org/gitweb?p=gnuk.git;a=summary
676
677 You can get it by:
678
679   $ git clone git://www.gniibe.org/gnuk.git/
680
681 or
682
683   $ git clone http://www.gniibe.org/git/gnuk.git/
684
685
686 Copy is available at: http://gitorious.org/gnuk
687
688
689 Information on the Web
690 ======================
691
692 Please visit: http://www.fsij.org/gnuk/
693
694
695 Your Contributions
696 ==================
697
698 FSIJ welcomes your contributions.  Please assign your copyright
699 to FSIJ (if possible).
700
701
702 Foot note
703 ==========
704 * NUK(R) is a registered trademark owend by MAPA GmbH, Germany.
705 --