update README
[gnuk/gnuk.git] / README
1 We migrate from ChibiOS/RT to Chopstix.  You need:
2
3     Edit .git/config to remove chibios reference
4     git rm --cached chibios
5
6
7
8 Gnuk - An Implementation of USB Cryptographic Token for GnuPG
9
10                                                           Version 1.1.0
11                                                              2013-12-XX
12                                                            Niibe Yutaka
13                                       Free Software Initiative of Japan
14
15 What's Gnuk?
16 ============
17
18 Gnuk is an implementation of USB cryptographic token for GNU Privacy
19 Guard.  Gnuk supports OpenPGP card protocol version 2, and it runs on
20 STM32F103 processor.
21
22 I wish that Gnuk will be a developer's soother who uses GnuPG.  I have
23 been nervous of storing secret key(s) on usual secondary storage.
24 There is a solution with OpenPGP card, but it is not the choice for
25 me, as card reader is not common device.  With Gnuk, this issue will
26 be solved by a USB token.
27
28 Please look at the graphics of "gnuk.svg" for the software name.  My
29 son used to be with his NUK(R), always, everywhere.  Now, I am with a
30 USB Cryptographic Token by "Gnuk", always, everywhere.
31
32
33 FAQ
34 ===
35
36 Q0: How Gnuk USB Token is superior than other solutions (OpenPGP
37     card 2.0, GPF Crypto Stick, etc.) ?
38     http://www.g10code.de/p-card.html
39     http://www.privacyfoundation.de/crypto_stick/
40 A0: Good points of Gnuk are:
41     * If you have skill of electronics and like DIY, you can build
42       Gnuk Token cheaper (see Q8-A8).
43     * You can study Gnuk to modify and to enhance.  For example, you
44       can implement your own authentication method with some sensor
45       such as an acceleration sensor.
46     * It is "of Free Software"; Gnuk is distributed under GPLv3+,
47             "by Free Software"; Gnuk development requires only Free Software
48                                 (GNU Toolchain, Python, etc.), 
49             "for Free Software"; Gnuk supports GnuPG.
50
51 Q1: What kind of key algorithm is supported?
52 A1: Gnuk version 1 only supports 2048-bit RSA.
53
54 Q2: How long does it take for digital signing?
55 A2: It takes a second and a half or so. 
56
57 Q3: What's your recommendation for target board?
58 A3: Orthodox choice is Olimex STM32-H103.
59     If you have skill of electronics and like DIY, STM32 part of STM8S
60     Discovery Kit might be the best choice.
61     FST-01 (Flying Stone Tiny 01) will be soon available for sale,
62     and it will be the best choice, hopefully.
63
64 Q4: What's version of GnuPG are you using?
65 A4: In Debian GNU/Linux system, I use gnupg 1.4.11-3 and gnupg-agent
66     2.0.18-2.  With older versions, you can only sign with SHA1.
67     See: http://www.fsij.org/gnuk/gnupg2-fixes-needed
68
69 Q5: What's version of pcscd and libccid are you using?
70 A5: In Debian GNU/Linux system, I use pcscd 1.5.5-4 and libccid 1.3.11-2,
71     which is in squeeze.  Note that you need to edit /etc/libccid_Info.plist
72     when using libccid (< 1.4.1).
73     Note that pcscd and libccid are optional, you can use Gnuk without them.
74
75 Q6: What kinds of hardware is required for development?
76 A6: You need a target board plus a JTAG/SWD debugger.  If you just
77     want to test Gnuk for target boards with DfuSe, JTAG debugger is
78     not the requirement.  Note that for real use, you need JTAG/SWD
79     debugger to enable flash ROM protection.
80
81 Q7: How much does it cost?
82 A7: Olimex STM32-H103 plus ARM-USB-TINY-H cost 70 Euro or so.
83
84 Q8: How much does it cost for DIY version?
85 A8: STM8S Discovery Kit costs 750 JPY (< $10 USD) only.  You can build
86     your own JTAG debugger using FTDI2232 module (1450 JPY), see:
87     http://www.fsij.org/gnuk/jtag_dongle_ftdi2232
88
89 Q9: I got an error like "gpg: selecting openpgp failed: ec=6.108", what's up?
90
91 A9: GnuPG's SCDaemon has problems for handling insertion/removal of
92     card/reader (problems are fixed in trunk, and backported to 2.0
93     branch, it will be 2.0.20).  When your newly inserted token is not
94     found by GnuPG, try killing scdaemon and let it to be invoked
95     again.  I do:
96
97          $ gpg-connect-agent "SCD KILLSCD" "SCD BYE" /bye
98
99     and confirm scdaemon doesn't exist, then,
100
101          $ gpg-connect-agent learn /bye
102
103 Qa: With GNOME 2, I can't use Gnuk Token for SSH.  How can we use it for SSH?
104 Aa: You need to deactivate seahorse-agent and gnome-keyring, but use
105     gpg-agant for the role of ssh-agent.  For gnome-keyring please do:
106
107       $ gconftool-2 --type bool --set /apps/gnome-keyring/daemon-components/ssh false
108
109 Qb: With GNOME 3, I can't use Gnuk Token at all.  Why?
110 Ab: That's because gnome-keyring-daemon interferes GnuPG.  Type:
111
112       $ gnome-session-properties
113
114     and at the tab of "Startup Programs", disable check buttons for
115     "GPG Password Agent" and "SSH Key Agent".
116
117 Qc: Do you know a good SWD debugger to connect FST-01 or something?
118 Ac: ST-Link/V2 is cheap one.  We have a tool/stlinkv2.py as flash ROM
119     writer program.
120
121
122 Release notes
123 =============
124
125 This is an experimental release in version 1.1 series of Gnuk.
126
127 While it is daily use for a year and a half, some newly introduced
128 features (including key generation and firmware upgrade) should be
129 considered experimental.
130
131 Tested features are:
132
133         * Personalization of the card
134           * Changing Login name, URL, Name, Sex, Language, etc.
135         * Password handling (PW1, RC, PW3)
136         * Key import for three types:
137           * key for digital signing
138           * key for decryption
139           * key for authentication
140         * PSO: Digital Signature
141         * PSO: Decipher
142         * INTERNAL AUTHENTICATE
143         * Changing value of password status bytes (0x00C4): forcesig
144         * Verify with pin pad
145         * Modify with pin pad
146         * Card holder certificate (read)
147         * Removal of keys
148         * Key generation on device side
149         * Overriding key import
150
151 Original features of Gnuk, tested lightly:
152
153         * OpenPGP card serial number setup
154         * Card holder certificate (write by UPDATE BINARY)
155         * Upgrading with "EXTERNAL AUTHENTICATE" by reGNUal
156
157 It is known not-working well:
158
159         * For some old versions of kernel and libccid, --enable-debug
160           can't work well.  Please make sure to disable DEBUG option
161           if it doesn't work well.
162
163         * It is known that the combination of libccid 1.4.1 (or newer)
164           with libusb 1.0.8 (or older) has a minor problem.  It is
165           rare but it is possible for USB communication to be failed,
166           because of a bug in libusb implementation.  Use libusbx
167           1.0.9 or newer, or don't use PC/SC, but use internal CCID
168           driver of GnuPG.
169
170
171 Targets
172 =======
173
174 We use Olimex STM32-H103 board and Flying Stone Tiny 01 (FST-01).  We
175 also use STM32 part of STM8S Discovery Kit.
176
177 With DfuSe support, STBee is also our targets.  But this target with
178 DfuSe is for experiment only, because it is impossible for DfuSe to
179 disable read from flash.  For real use, please consider killing DfuSe
180 and enabling read protection using JTAG debugger.
181
182 For PIN-pad support, I connect a consumer IR receive module to FST-01
183 and STM8S Discovery Kit, and use controller for TV.  PIN verification
184 is supported by this configuration.  Yes, it is not secure at all,
185 since it is very easy to monitor IR output of the controllers.  It is
186 just an experiment.  Note that hardware needed for this experiment is
187 only a consumer IR receive module which is as cheap as 50 JPY.
188
189 Note that you need pinpad support for GnuPG to use PIN-pad enabled
190 Gnuk.  The pinpad support for GnuPG is only supported in version 2.
191
192
193 Souce code
194 ==========
195
196 Gnuk source code is under src/ directory.
197
198 Note that SHA-2 hash function implementation, src/sha256.c, is based
199 on the original implementation by Dr. Brian Gladman.  See:
200
201   http://gladman.plushost.co.uk/oldsite/cryptography_technology/sha/index.php
202
203
204 License
205 =======
206
207 It is distributed under GNU General Public Licence version 3 or later
208 (GPLv3+).  Please see src/COPYING.
209
210 Please note that it is distributed with external source code too.
211 Please read relevant licenses for external source code as well.
212
213 The author(s) of Gnuk expect users of Gnuk will be able to access the
214 source code of Gnuk, so that users can study the code and can modify
215 if needed.  This doesn't mean person who has a USB Token by Gnuk
216 should be able to access everything on the Token, regardless of its
217 protections.  Private keys, and other information should be protected
218 properly.
219
220
221 External source code
222 ====================
223
224 Gnuk is distributed with external source code.
225
226 * chopstx/  -- Chopstx 0.04
227
228   We use Chopstx as the kernel for Gnuk.
229
230   Chopstx is distributed under GPLv3+ (with a special exception).
231
232
233 * polarssl/  -- PolarSSL 1.2.10
234
235   Souce code taken from: http://polarssl.org/
236
237   We use PolarSSL for RSA computation, and AES encryption/decryption.
238
239   PolarSSL is distributed under GPLv2+.  We use PolarSSL under GPLv3
240   as our options.
241
242   The file include/polarssl/bn_mul.h is heavily modified for ARM
243   Cortex-M3.
244
245   The function rsa_private in polarssl/library/rsa.c is modified so
246   that it doesn't check T against N.  The function rsa_pkcs1_sign is
247   modified to avoid warnings in case of !POLARSSL_PKCS1_V21.
248
249   The functions rsa_pkcs1_verify and rsa_rsassa_pkcs1_v15_verify in
250   include/polarssl/rsa.h and polarssl/library/rsa.c are modified
251   (fixed) for last argument SIG, as the memory at SIG aren't modified
252   by those routines.
253
254   The constant POLARSSL_MPI_MAX_SIZE in include/polarssl/bignum.h is
255   modified for 2048-bit keys only Gnuk.
256
257   The function mpi_mul_hlp in library/bignum.c is modified for more
258   optimization for ARM Cortex-M3.  Functions mpi_montred, mpi_sub_hlp,
259   mpi_sub_abs, mpi_mul_mpi, mpi_montmul, and mpi_exp are modified
260   to avoid side channel attacks.  Note that we don't use RSA-blinding
261   technique for Gnuk.  Function mpi_gen_prime and mpi_is_prime are
262   modified to use Fouque-Tibouchi method.
263
264   The file library/aes.c is modified so that some constants can
265   go to .sys section.
266
267   The file include/polarssl/config.h are modified not to define
268   POLARSSL_HAVE_LONGLONG to avoid linking libgcc, to define
269   POLARSSL_AES_ROM_TABLES to have AES tables, not to define
270   POLARSSL_CIPHER_MODE_CTR, POLARSSL_FS_IO, POLARSSL_PKCS1_V21,
271   POLARSSL_SELF_TEST, and POLARSSL_PADLOCK_C, and only define
272   POLARSSL_GENPRIME when defined KEYGEN_SUPPORT.
273
274
275 USB vendor ID and product ID (USB device ID)
276 ============================================
277
278 When you have a vender ID and assign a product ID for Gnuk, edit the
279 file GNUK_USB_DEVICE_ID and add an entry for yours.  In this case,
280 please contact Niibe, so that it is listed to the file in the official
281 release of the source code.
282
283 When you are modifing Gnuk and installing the binary to device, you
284 should replace the vendor string and serial number to yours (in the
285 file GNUK_USB_DEVICE_ID and SERIALNO of the script of src/configure),
286 so that users can see it's not by original vendor, and it is modified
287 version.
288
289 FSIJ allows you to use USB device ID of FSIJ (234b:0000) for devices
290 with Gnuk under one of following conditions:
291
292   * For everyone for experimental purpose:
293
294     - You must not distribute a binary with FSIJ's USB device ID, but
295       must use the binary by yourself only for your experiment.  Note
296       that "Distributing binary" includes distributing a device which
297       holds the binary.
298
299   * For general individuals:
300
301     - You must use your Gnuk device with a card serial number which is
302       *not* by FSIJ.  Easy one would be a card serial number generated
303       by chip unique ID.
304
305   * For individuals with explicit permission from FSIJ.
306
307     - You should have an assigned card serial number by FSIJ,
308       please use that number for your device.
309       (There a file 'GNUK_SERIAL_NUMBER' in the official release.)
310
311 FSIJ could give companies or business entities "second source
312 manufacturer" license to use USB device ID of FSIJ for devices with
313 unmodified version of Gnuk, provided they support Free Software and
314 respect users' freedom for computing.  Please ask FSIJ for the
315 license.
316
317 Otherwise, companies which want to distribute Gnuk devices, please use
318 your own USB vendor ID and product ID.  Please replace vendor string
319 and possibly product string to yours, when you modify Gnuk.
320
321
322 Host Requirements
323 =================
324
325 For GNU/Linux, PC/SC service is an option, you can use GnuPG's
326 internal CCID driver instead.  If you chose using PC/SC service,
327 libccid version >= 1.3.11 is recommended for GNU/Linux.
328
329 I think that it should not be requirment but the kernel version of my use is:
330 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
331
332 Linux 2.6.30 is known *NOT* working well with DEBUG option.
333 Linux 2.6.24 is known working well with DEBUG option.
334
335
336 How to compile
337 ==============
338
339 You need GNU toolchain and newlib for 'arm-none-eabi' target.
340
341 There is "gcc-arm-embedded" project.  See:
342
343     https://launchpad.net/gcc-arm-embedded/
344
345
346 Change directory to `src':
347
348   $ cd gnuk-VERSION/src
349
350 Then, run `configure':
351
352   $ ./configure --vidpid=<VID:PID>
353
354 Here, you need to specify USB vendor ID and product ID.  For FSIJ's,
355 it's: --vidpid=234b:0000 .  Please read section 'USB vendor ID and
356 product ID' above.
357
358 Type:
359
360   $ make
361
362 Then, we will have "gnuk.elf" under src/build directory.
363
364
365 How to install
366 ==============
367
368 Olimex STM32-H103 board
369 -----------------------
370
371 If you are using Olimex JTAG-Tiny, type following to invoke OpenOCD:
372
373   $ openocd -f interface/olimex-jtag-tiny.cfg -f board/olimex_stm32_h103.cfg
374
375 Then, with another terminal, type following to write "gnuk.elf" to Flash ROM:
376
377   $ telnet localhost 4444
378   > reset halt
379   > flash write_image erase gnuk.elf
380   > reset
381   > exit
382   $ 
383
384
385 Flying Stone Tiny 01
386 --------------------
387
388 If you are using Flying Stone Tiny 01, you need a SWD writer.  I am
389 using revision 946 of Simon Qian's Versaloon.
390
391     svn checkout -r 946 http://vsprog.googlecode.com/svn/trunk/
392
393 For OpenOCD, we need unofficial patch.
394
395 See the article of Versaloon Forum:
396
397     http://www.versaloon.com/bbs/viewtopic.php?p=16179
398
399
400 Type following to invoke OpenOCD:
401
402   $ openocd -f interface/vsllink.cfg -c "transport select swd" -c "swd_mode 2" -f target/stm32f1x.cfg
403
404 Then, with another terminal, type following to write "gnuk.elf" to Flash ROM:
405
406   $ telnet localhost 4444
407   > reset halt
408   > flash write_image erase gnuk.elf
409   > reset
410   > exit
411   $ 
412
413 OpenOCD 0.6.1 now supports ST-Link/V2.  We can use it:
414
415   $ openocd -f interface/stlink-v2.cfg -f target/stm32f1x_stlink.cfg
416
417 But it doesn't support option bytes handling (protection) yet.
418
419
420 STM8S Discovery Kit
421 -------------------
422
423 If you are using FTDI-2232D module and the connection is standard, type:
424
425   $ openocd -f interface/openocd-usb.cfg -f target/stm32f1x.cfg
426
427 Initially, the flash ROM of the chip is protected.  you need to do:
428
429   $ telnet localhost 4444
430   > reset halt
431   > stm32f1x unlock 0
432   > reset
433   > shutdown
434   $ 
435
436 and re-connect the board.  Note that power-off / power-on sequence is
437 required to reset flash ROM.
438
439 Then, invoke OpenOCD again and telnet to connect OpenCD and write
440 image as above example of Olimex STM32-H103.
441
442
443 STBee
444 -----
445
446 Reset the board with "USER" switch pushed.  Type following to write
447 to flash:
448
449   # cd ../tool
450   # ./dfuse.py ../src/build/gnuk.hex
451
452 Then, reset the board.
453
454
455 How to protect flash ROM
456 ========================
457
458 Invoke your OpenOCD and type:
459
460   $ telnet localhost 4444
461   > reset halt
462   > stm32f1x lock 0
463   > reset
464   > shutdown
465
466 After power-off / power-on sequence, the contents of flash ROM cannot
467 be accessible from JTAG debugger.
468
469 Note that it would be still possible for some implementation of DfuSe
470 to access the contents.  If you want to protect, killing DfuSe and
471 accessing by JTAG debugger is recommended.
472
473
474 How to configure
475 ================
476
477 You need python and pyscard (python-pyscard package in Debian) or
478 PyUSB (python-usb package in Debian).
479
480 (1) [pyscard] Stop scdaemon
481     [PyUSB] Stop the pcsc daemon.
482
483 If scdaemon is running, please kill it, or you will get "Smartcard
484 Exception" by "Sharing violation".
485
486   $ gpg-connect-agent "SCD KILLSCD" "SCD BYE" /bye
487
488 In case of PyUSB tool, you need to stop pcscd.
489
490   # /etc/init.d/pcscd stop
491
492
493 (2) [Optional] Write fixed serial number
494
495 If you use fixed serial number in the file 'GNUK_SERIAL_NUMBER', you can do:
496
497   $ EMAIL=<YOUR-EMAIL-ADDRESS> ../tool/gnuk_put_binary.py -s ../GNUK_SERIAL_NUMBER
498   Writing serial number
499   ...
500
501 (3) [Optional] Write card holder certificate
502
503 If you have card holder certificate binary file, you can do:
504
505   $ ../tool/gnuk_put_binary.py ../../<YOUR-CERTIFICATE>.bin
506   ../../<YOUR-CERTIFICATE>.bin: <LENGTH-OF-YOUR-CERTIFICATE>
507   Updating card holder certificate
508   ...
509
510
511 How to run
512 ==========
513
514 Debug enabled
515 -------------
516
517 If you compiled with --enable-debug option, Gnuk has two interfaces
518 (one is CCID/ICCD device and another is virtual COM port).  Open
519 virtual COM port by:
520
521   $ cu -l /dev/ttyACM0
522
523 and you will see debug output of Gnuk.
524
525
526 Libccid fix needed
527 ------------------
528
529 For libccid (< 1.4.1), we need following change:
530
531 --- /etc/libccid_Info.plist.dpkg-dist   2009-07-29 06:50:20.000000000 +0900
532 +++ /etc/libccid_Info.plist     2010-09-05 09:09:49.000000000 +0900
533 @@ -104,6 +104,7 @@
534  
535         <key>ifdVendorID</key>
536         <array>
537 +               <string>0x234B</string>
538                 <string>0x08E6</string>
539                 <string>0x08E6</string>
540                 <string>0x08E6</string>
541 @@ -237,6 +238,7 @@
542  
543         <key>ifdProductID</key>
544         <array>
545 +               <string>0x0000</string>
546                 <string>0x2202</string>
547                 <string>0x3437</string>
548                 <string>0x3438</string>
549 @@ -370,6 +372,7 @@
550  
551         <key>ifdFriendlyName</key>
552         <array>
553 +               <string>FSIJ USB Token</string>
554                 <string>Gemplus Gem e-Seal Pro</string>
555                 <string>Gemplus GemPC Twin</string>
556                 <string>Gemplus GemPC Key</string>
557 ------------------
558
559 This entry has been added into libccid 1.4.1 already ([r5425]).
560
561
562 Testing Gnuk
563 ------------
564
565 Type following command to see Gnuk runs:
566
567   $ gpg --card-status
568
569
570 Besides, there is a functinality test under test/ directory.  See
571 test/README.
572
573
574 Personalize the Token and import keys
575 -------------------------------------
576
577 You can personalize the token, putting your information like: Name,
578 Login name, Sex, Languages, URL, etc., and password.  To do so, GnuPG
579 command is:
580
581   $ gpg --card-edit
582
583 Note that the factory setting of user password is "123456" and admin
584 password is "12345678" as the specification.
585
586 It is recommended to create your keys on your computer, and import
587 them to Gnuk Token.  After you create your keys (they must be 2048-bit
588 RSA), you can import them.
589
590 Gnuk supports key generation, but this feature is young and should be
591 considered experimental.
592
593 For detail, please see doc/note/DEMO and doc/note/DEMO-2.
594
595 Note that it make sense to preserve your keys on your computer so that
596 you can import the keys (again) to (possibly another) Gnuk Token.  In
597 this case, you can use GnuPG's option to specify the home directory by
598 --homedir.
599
600 After creating keys on your computer by:
601
602   $ gpg --gen-key
603   ...
604
605 Copy directory which contains your secret keys to new directory named
606 <gpgdir-with-your-secret-keys>:
607
608   $ cp -pa $HOME/.gnupg <gpgdir-with-your-secret-keys>
609
610 Then, import keys by:
611
612   $ gpg --edit-key <YOUR-KEYID>
613
614 While your $HOME/.gnupg now doesn't have your secret keys after
615 import, <gpgdir-with-your-secret-keys> still has them.  You can again
616 import them by:
617
618   $ gpg --homedir=<gpgdir-with-your-secret-keys> --edit-key <YOUR-KEYID>
619
620 Note that you *should not* save changes this time to preserve keys
621 on your computer.  The session goes like this:
622
623   gpg> quit
624   Save changes? (y/N) n
625   Quit without saving? (y/N) y
626
627
628
629 How to debug
630 ============
631
632 We can use GDB.
633
634   $ arm-none-eabi-gdb gnuk.elf
635
636
637 Inside GDB, we can connect OpenOCD by:
638
639   (gdb) target remote localhost:3333
640
641
642 You can see the output of PCSCD:
643
644   # /etc/init.d/pcscd stop
645   # LIBCCID_ifdLogLevel=7 /usr/sbin/pcscd --debug --foreground
646
647
648 You can observe the traffic of USB using "usbmon".  See the file:
649 linux/Documentation/usb/usbmon.txt
650
651
652 Firmware update
653 ===============
654
655 See doc/note/firmware-update.
656
657
658 Git Repositories
659 ================
660
661 You can browse at: http://www.gniibe.org/gitweb?p=gnuk.git;a=summary
662
663 You can get it by:
664
665   $ git clone git://www.gniibe.org/gnuk.git/
666
667 or
668
669   $ git clone http://www.gniibe.org/git/gnuk.git/
670
671
672 Copy is available at: http://gitorious.org/gnuk
673
674
675 Information on the Web
676 ======================
677
678 Please visit: http://www.fsij.org/gnuk/
679
680
681 Your Contributions
682 ==================
683
684 FSIJ welcomes your contributions.  Please assign your copyright
685 to FSIJ (if possible).
686
687
688 Foot note
689 ==========
690 * NUK(R) is a registered trademark owend by MAPA GmbH, Germany.
691 --