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