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