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