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