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