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