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