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