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