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