remove PC/SC tools
[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 Build system and Host system
212 ============================
213
214 Makefile is written for GNU make.  You need Bash 4.x for configure.
215
216 If your bash is not installed as /bin/bash, you need to run configure
217 script prepending 'bash' before './configure'.
218
219 Some tools are written in Python.  If your Python is not installed as
220 /usr/bin/python, please prepend 'python' for your command invocation.
221 Python 2.7 and PyUSB 0.4.3 is assumed.
222
223
224 Souce code
225 ==========
226
227 Gnuk source code is under src/ directory.
228
229 Note that SHA-2 hash function implementation, src/sha256.c, is based
230 on the original implementation by Dr. Brian Gladman.  See:
231
232   http://gladman.plushost.co.uk/oldsite/cryptography_technology/sha/index.php
233
234
235 License
236 =======
237
238 It is distributed under GNU General Public Licence version 3 or later
239 (GPLv3+).  Please see src/COPYING.
240
241 Please note that it is distributed with external source code too.
242 Please read relevant licenses for external source code as well.
243
244 The author(s) of Gnuk expect users of Gnuk will be able to access the
245 source code of Gnuk, so that users can study the code and can modify
246 if needed.  This doesn't mean person who has a Gnuk Token should be
247 able to access everything on the Token, regardless of its protections.
248 Private keys, and other information should be protected properly.
249
250
251 External source code
252 ====================
253
254 Gnuk is distributed with external source code.
255
256 * chopstx/  -- Chopstx 0.07
257
258   We use Chopstx as the kernel for Gnuk.
259
260   Chopstx is distributed under GPLv3+ (with a special exception).
261
262
263 * polarssl/  -- based on PolarSSL 1.2.10 (now mbedTLS)
264
265   Souce code taken from: http://polarssl.org/
266
267   We use PolarSSL for RSA computation, and AES encryption/decryption.
268
269   PolarSSL is distributed under GPLv2+.  We use PolarSSL under GPLv3
270   as our options.
271
272   The file include/polarssl/bn_mul.h is heavily modified for ARM
273   Cortex-M3.
274
275   The function rsa_private in polarssl/library/rsa.c is modified so
276   that it doesn't check T against N.  The function rsa_pkcs1_sign is
277   modified to avoid warnings in case of !POLARSSL_PKCS1_V21.
278
279   The functions rsa_pkcs1_verify and rsa_rsassa_pkcs1_v15_verify in
280   include/polarssl/rsa.h and polarssl/library/rsa.c are modified
281   (fixed) for last argument SIG, as the memory at SIG aren't modified
282   by those routines.
283
284   The constant POLARSSL_MPI_MAX_SIZE in include/polarssl/bignum.h is
285   modified for 2048-bit keys only Gnuk.
286
287   The function mpi_mul_hlp in library/bignum.c is modified for more
288   optimization for ARM Cortex-M3.  Functions mpi_montred, mpi_sub_hlp,
289   mpi_sub_abs, mpi_mul_mpi, mpi_montmul, and mpi_exp_mod are modified
290   to avoid side channel attacks.  Note that we don't use RSA-blinding
291   technique for Gnuk.  Function mpi_gen_prime and mpi_is_prime are
292   modified to use Fouque-Tibouchi method.  Function mpi_exp_mod is
293   modified to use new function mpi_montsqr for speed up.
294
295   The file library/aes.c is modified so that some constants can
296   go to .sys section.
297
298   The file include/polarssl/config.h are modified not to define
299   POLARSSL_HAVE_LONGLONG to avoid linking libgcc, to define
300   POLARSSL_AES_ROM_TABLES to have AES tables, not to define
301   POLARSSL_CIPHER_MODE_CTR, POLARSSL_FS_IO, POLARSSL_PKCS1_V21,
302   POLARSSL_SELF_TEST, and POLARSSL_PADLOCK_C, and only define
303   POLARSSL_GENPRIME when defined KEYGEN_SUPPORT.
304
305
306 USB vendor ID and product ID (USB device ID)
307 ============================================
308
309 When you have a vender ID and assign a product ID for Gnuk, edit the
310 file GNUK_USB_DEVICE_ID and add an entry for yours.  In this case,
311 please contact Niibe, so that it is listed to the file in the official
312 release of the source code.
313
314 When you are modifing Gnuk and installing the binary to device, you
315 should replace the vendor string and serial number to yours (in the
316 file GNUK_USB_DEVICE_ID and SERIALNO of the script of src/configure),
317 so that users can see it's not by original vendor, and it is modified
318 version.
319
320 FSIJ allows you to use USB device ID of FSIJ (234b:0000) for devices
321 with Gnuk under one of following conditions:
322
323   * For everyone for experimental purpose:
324
325     - You must not distribute a binary with FSIJ's USB device ID, but
326       must use the binary by yourself only for your experiment.  Note
327       that "Distributing binary" includes distributing a device which
328       holds the binary.
329
330   * For general individuals:
331
332     - You must use your Gnuk device with a card serial number which is
333       *not* by FSIJ.  Easy one would be a card serial number generated
334       by chip unique ID.
335
336   * For individuals with explicit permission from FSIJ.
337
338     - You should have an assigned card serial number by FSIJ,
339       please use that number for your device.
340       (There a file 'GNUK_SERIAL_NUMBER' in the official release.)
341
342 FSIJ could give companies or business entities "second source
343 manufacturer" license to use USB device ID of FSIJ for devices with
344 unmodified version of Gnuk, provided they support Free Software and
345 respect users' freedom for computing.  Please ask FSIJ for the
346 license.
347
348 Otherwise, companies which want to distribute Gnuk devices, please use
349 your own USB vendor ID and product ID.  Please replace vendor string
350 and possibly product string to yours, when you modify Gnuk.
351
352
353 Host Requirements
354 =================
355
356 For GNU/Linux, PC/SC service is an option, you can use GnuPG's
357 internal CCID driver instead.  If you chose using PC/SC service,
358 libccid version >= 1.3.11 is recommended for GNU/Linux.
359
360
361 How to compile
362 ==============
363
364 You need GNU toolchain and newlib for 'arm-none-eabi' target.
365
366 There is "gcc-arm-embedded" project.  See:
367
368     https://launchpad.net/gcc-arm-embedded/
369
370
371 Change directory to `src':
372
373   $ cd gnuk-VERSION/src
374
375 Then, run `configure':
376
377   $ ./configure --vidpid=<VID:PID>
378
379 Here, you need to specify USB vendor ID and product ID.  For FSIJ's,
380 it's: --vidpid=234b:0000 .  Please read section 'USB vendor ID and
381 product ID' above.
382
383
384 Then, type:
385
386   $ make
387
388 Then, we will have "gnuk.elf" under src/build directory.
389
390
391 How to install
392 ==============
393
394 Olimex STM32-H103 board
395 -----------------------
396
397 If you are using Olimex JTAG-Tiny, type following to invoke OpenOCD:
398
399   $ openocd -f interface/ftdi/olimex-jtag-tiny.cfg -f board/olimex_stm32_h103.cfg
400
401 Then, with another terminal, type following to write "gnuk.elf" to Flash ROM:
402
403   $ telnet localhost 4444
404   > reset halt
405   > flash write_image erase gnuk.elf
406   > reset
407   > exit
408   $ 
409
410
411 Flying Stone Tiny 01
412 --------------------
413
414 If you are using Flying Stone Tiny 01, you need a SWD writer.
415
416 OpenOCD 0.9 now supports ST-Link/V2.  We can use it:
417
418   $ openocd -f interface/stlink-v2.cfg -f target/stm32f1x_stlink.cfg
419
420
421
422 STBee
423 -----
424
425 Reset the board with "USER" switch pushed.  Type following to write
426 to flash:
427
428   # cd ../tool
429   # ./dfuse.py ../src/build/gnuk.hex
430
431 Then, reset the board.
432
433
434 How to protect flash ROM
435 ========================
436
437 Invoke your OpenOCD and type:
438
439   $ telnet localhost 4444
440   > reset halt
441   > stm32f1x lock 0
442   > reset
443   > shutdown
444
445 After power-off / power-on sequence, the contents of flash ROM cannot
446 be accessible from JTAG debugger.
447
448 Note that it would be still possible for some implementation of DfuSe
449 to access the contents.  If you want to protect, killing DfuSe and
450 accessing by JTAG debugger is recommended.
451
452
453 How to configure
454 ================
455
456 You need python and pyscard (python-pyscard package in Debian) or
457 PyUSB 0.4.3 (python-usb package in Debian).
458
459 (1) [pyscard] Stop scdaemon
460     [PyUSB] Stop the pcsc daemon.
461
462 If scdaemon is running, please kill it, or you will get "Smartcard
463 Exception" by "Sharing violation".
464
465   $ gpg-connect-agent "SCD KILLSCD" "SCD BYE" /bye
466
467 In case of PyUSB tool, you need to stop pcscd.
468
469   # /etc/init.d/pcscd stop
470
471
472 (2) [Optional] Write fixed serial number
473
474 If you use fixed serial number in the file 'GNUK_SERIAL_NUMBER', you can do:
475
476   $ EMAIL=<YOUR-EMAIL-ADDRESS> ../tool/gnuk_put_binary_usb.py -s ../GNUK_SERIAL_NUMBER
477   Writing serial number
478   ...
479
480 (3) [Optional] Write card holder certificate
481
482 If you have card holder certificate binary file, you can do:
483
484   $ ../tool/gnuk_put_binary_usb.py ../../<YOUR-CERTIFICATE>.bin
485   ../../<YOUR-CERTIFICATE>.bin: <LENGTH-OF-YOUR-CERTIFICATE>
486   Updating card holder certificate
487   ...
488
489
490 How to run
491 ==========
492
493 Debug enabled
494 -------------
495
496 If you compiled with --enable-debug option, Gnuk has two interfaces
497 (one is CCID/ICCD device and another is virtual COM port).  Open
498 virtual COM port by:
499
500   $ cu -l /dev/ttyACM0
501
502 and you will see debug output of Gnuk.
503
504
505 Testing Gnuk
506 ------------
507
508 Type following command to see Gnuk runs:
509
510   $ gpg --card-status
511
512
513 Besides, there is a functionality test under test/ directory.  See
514 test/README.
515
516
517 Personalize the Token, import keys, and change the password
518 -----------------------------------------------------------
519
520 You can personalize the token, putting your information like: Name,
521 Login name, Sex, Languages, URL.  To do so, GnuPG command is:
522
523   $ gpg --card-edit
524
525 Note that the factory setting of user password is "123456" and admin
526 password is "12345678" as the specification.
527
528 It is recommended to create your keys on your computer, and import
529 them to Gnuk Token.  After you create your keys (they must be 2048-bit
530 RSA), you can import them.
531
532 Gnuk supports key generation, but this feature is young and should be
533 considered experimental.
534
535 For detail, please see documentation under doc/.  You can see the HTML
536 version at: http://www.fsij.org/doc-gnuk/
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: https://anonscm.debian.org/cgit/gnuk/gnuk/
572
573 You can get it by:
574  
575     $ git clone git://anonscm.debian.org/gnuk/gnuk/gnuk.git
576
577 It's also available at: www.gniibe.org
578 You can browse at: http://git.gniibe.org/gitweb?p=gnuk/gnuk.git;a=summary
579
580 I put Chopstx as a submodule of Git.  Please do this:
581
582   $ git submodule init
583   $ git submodule update
584
585 We have migrated from ChibiOS/RT to Chopstx.  If you have old code of
586 ChibiOS/RT, you need:
587
588     Edit .git/config to remove chibios reference
589     git rm --cached chibios
590
591
592 Information on the Web
593 ======================
594
595 Please visit: http://www.fsij.org/gnuk/
596
597 Please see the FST-01 support pages:
598
599     http://www.gniibe.org/category/fst-01.html
600
601 Please consider to join Gnuk-users mailing list:
602
603     https://lists.alioth.debian.org/mailman/listinfo/gnuk-users
604
605
606 Your Contributions
607 ==================
608
609 FSIJ welcomes your contributions.  Please assign your copyright
610 to FSIJ (if possible).
611
612
613 Foot note
614 ==========
615
616 * NUK(R) is a registered trademark owend by MAPA GmbH, Germany.
617 --