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