Bignum fixes
[gnuk/gnuk.git] / README
1 Gnuk - An Implementation of USB Cryptographic Token for GnuPG
2
3                                                           Version 1.1.9
4                                                              2015-09-18
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.9, 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 modern GnuPG with
19 development version of libgcrypt.
20
21 It also supports RSA-4096 experimentally, but users should know that
22 it takes more than 8 second to sign/decrypt.
23
24 You will not able to keep using Curve25519 keys, as the key format is
25 subject to change.
26
27
28 What's Gnuk?
29 ============
30
31 Gnuk is an implementation of USB cryptographic token for GNU Privacy
32 Guard.  Gnuk supports OpenPGP card protocol version 3, and it runs on
33 STM32F103 processor.
34
35 I wish that Gnuk will be a developer's soother who uses GnuPG.  I have
36 been nervous of storing secret key(s) on usual secondary storage.
37 There is a solution with OpenPGP card, but it is not the choice for
38 me, as card reader is not common device.  With Gnuk, this issue will
39 be solved by a USB token.
40
41 Please look at the graphics of "gnuk.svg" for the software name.  My
42 son used to be with his NUK(R), always, everywhere.  Now, I am with a
43 USB Cryptographic Token by "Gnuk", always, everywhere.
44
45
46 FAQ
47 ===
48
49 Q0: How Gnuk USB Token is superior than other solutions (OpenPGP
50     card 2.0, YubiKey, etc.) ?
51     http://www.g10code.de/p-card.html
52     https://www.yubico.com/
53 A0: Good points of Gnuk are:
54     * If you have skill of electronics and like DIY, you can build
55       Gnuk Token cheaper (see Q8-A8).
56     * You can study Gnuk to modify and to enhance.  For example, you
57       can implement your own authentication method with some sensor
58       such as an acceleration sensor.
59     * It is "of Free Software"; Gnuk is distributed under GPLv3+,
60             "by Free Software"; Gnuk development requires only Free Software
61                                 (GNU Toolchain, Python, etc.), 
62             "for Free Software"; Gnuk supports GnuPG.
63
64 Q1: What kind of key algorithm is supported?
65 A1: Gnuk version 1.0 only supports RSA-2048.
66     Development version of Gnuk (1.1.x) supports 256-bit ECDSA and EdDSA,
67     as well as RSA 4096-bit.  But it takes long time to sign with RSA-4096.
68
69 Q2: How long does it take for digital signing?
70 A2: It takes a second and a half or so for RSA-2048. 
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.x in
81     experimental.
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     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.
143
144
145 Release notes
146 =============
147
148 This is ninth experimental release in version 1.1 series of Gnuk.
149
150 While it is daily use by its developer, some newly introduced features
151 (including ECDSA/EdDSA/ECDH, key generation and firmware upgrade)
152 should be considered experimental.  ECDSA/EdDSA/ECDH is really
153 experimental.  Further, ECDH on Curve25519 is much experimental.  You
154 won't be able to keep using the key, since the key format of GnuPG is
155 not defined and it's subject to change.
156
157 Tested features are:
158
159         * Personalization of the card
160           * Changing Login name, URL, Name, Sex, Language, etc.
161         * Password handling (PW1, RC, PW3)
162         * Key import for three types:
163           * key for digital signing
164           * key for decryption
165           * key for authentication
166         * PSO: Digital Signature
167         * PSO: Decipher
168         * INTERNAL AUTHENTICATE
169         * Changing value of password status bytes (0x00C4): forcesig
170         * Verify with pin pad
171         * Modify with pin pad
172         * Card holder certificate (read)
173         * Removal of keys
174         * Key generation on device side
175         * Overriding key import
176
177 Original features of Gnuk, tested lightly:
178
179         * OpenPGP card serial number setup
180         * Card holder certificate (write by UPDATE BINARY)
181         * Upgrading with "EXTERNAL AUTHENTICATE" by reGNUal
182
183 It is known not-working well:
184
185         * It is known that the combination of libccid 1.4.1 (or newer)
186           with libusb 1.0.8 (or older) has a minor problem.  It is
187           rare but it is possible for USB communication to be failed,
188           because of a bug in libusb implementation.  Use libusbx
189           1.0.9 or newer, or don't use PC/SC, but use internal CCID
190           driver of GnuPG.
191
192
193 Targets
194 =======
195
196 We use Olimex STM32-H103 board and Flying Stone Tiny 01 (FST-01).
197
198 With DfuSe support, STBee is also our targets.  But this target with
199 DfuSe is for experiment only, because it is impossible for DfuSe to
200 disable read from flash.  For real use, please consider killing DfuSe
201 and enabling read protection using JTAG debugger.
202
203 For experimental PIN-pad support, I connect a consumer IR receive
204 module to FST-01, and use controller for TV.  PIN verification is
205 supported by this configuration.  Yes, it is not secure at all, since
206 it is very easy to monitor IR output of the controllers.  It is just
207 an experiment.  Note that hardware needed for this experiment is only
208 a consumer IR receive module which is as cheap as 50 JPY.
209
210 Note that you need pinpad support for GnuPG to use PIN-pad enabled
211 Gnuk.  The pinpad support for GnuPG is only available in version 2.
212
213
214 Build system and Host system
215 ============================
216
217 Makefile is written for GNU make.  You need Bash 4.x for configure.
218
219 If your bash is not installed as /bin/bash, you need to run configure
220 script prepending 'bash' before './configure'.
221
222 Some tools are written in Python.  If your Python is not installed as
223 /usr/bin/python, please prepend 'python' for your command invocation.
224 Python 2.7 and PyUSB 0.4.3 is assumed.
225
226
227 Souce code
228 ==========
229
230 Gnuk source code is under src/ directory.
231
232 Note that SHA-2 hash function implementation, src/sha256.c, is based
233 on the original implementation by Dr. Brian Gladman.  See:
234
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 0.10
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
309 USB vendor ID and product ID (USB device ID)
310 ============================================
311
312 When you have a vendor ID and assign a product ID for Gnuk, edit the
313 file GNUK_USB_DEVICE_ID and add an entry for yours.  In this case,
314 please contact Niibe, so that it is listed to the file in the official
315 release of the source code.
316
317 When you are modifing Gnuk and installing the binary to device, you
318 should replace the vendor string and serial number to yours (in the
319 file GNUK_USB_DEVICE_ID and SERIALNO of the script of src/configure),
320 so that users can see it's not by original vendor, and it is modified
321 version.
322
323 FSIJ allows you to use USB device ID of FSIJ (234b:0000) for devices
324 with Gnuk under one of following conditions:
325
326   * For everyone for experimental purpose:
327
328     - You must not distribute a binary with FSIJ's USB device ID, but
329       must use the binary by yourself only for your experiment.  Note
330       that "Distributing binary" includes distributing a device which
331       holds the binary.
332
333   * For general individuals:
334
335     - You must use your Gnuk device with a card serial number which is
336       *not* by FSIJ.  Easy one would be a card serial number generated
337       by chip unique ID.
338
339   * For individuals with explicit permission from FSIJ.
340
341     - You should have an assigned card serial number by FSIJ,
342       please use that number for your device.
343       (There a file 'GNUK_SERIAL_NUMBER' in the official release.)
344
345 FSIJ could give companies or business entities "second source
346 manufacturer" license to use USB device ID of FSIJ for devices with
347 unmodified version of Gnuk, provided they support Free Software and
348 respect users' freedom for computing.  Please ask FSIJ for the
349 license.
350
351 Otherwise, companies which want to distribute Gnuk devices, please use
352 your own USB vendor ID and product ID.  Please replace vendor string
353 and possibly product string to yours, when you modify Gnuk.
354
355
356 Host Requirements
357 =================
358
359 For GNU/Linux, PC/SC service is an option, you can use GnuPG's
360 internal CCID driver instead.  If you chose using PC/SC service,
361 libccid version >= 1.3.11 is recommended for GNU/Linux.
362
363
364 How to compile
365 ==============
366
367 You need GNU toolchain and newlib for 'arm-none-eabi' target.
368
369 On Debian we can install the packages of gcc-arm-none-eabi,
370 gdb-arm-none-eabi and its friends.  I'm using:
371
372         binutils-arm-none-eabi  2.25-5+5+b1
373         gcc-arm-none-eabi       15:4.9.3+svn227297-1
374         gdb-arm-none-eabi       7.7.1+dfsg-5+8
375         libnewlib-arm-none-eabi 2.2.0+git20150830.5a3d536-1
376
377 Or else, see https://launchpad.net/gcc-arm-embedded for preparation of
378 GNU Toolchain for 'arm-none-eabi' target.
379
380 Change directory to `src':
381
382   $ cd gnuk-VERSION/src
383
384 Then, run `configure':
385
386   $ ./configure --vidpid=<VID:PID>
387
388 Here, you need to specify USB vendor ID and product ID.  For FSIJ's,
389 it's: --vidpid=234b:0000 .  Please read section 'USB vendor ID and
390 product ID' above.
391
392
393 Then, type:
394
395   $ make
396
397 Then, we will have "gnuk.elf" under src/build directory.
398
399
400 How to install
401 ==============
402
403 Olimex STM32-H103 board
404 -----------------------
405
406 If you are using Olimex JTAG-Tiny, type following to invoke OpenOCD:
407
408   $ openocd -f interface/ftdi/olimex-jtag-tiny.cfg -f board/olimex_stm32_h103.cfg
409
410 Then, with another terminal, type following to write "gnuk.elf" to Flash ROM:
411
412   $ telnet localhost 4444
413   > reset halt
414   > flash write_image erase gnuk.elf
415   > reset
416   > exit
417   $ 
418
419
420 Flying Stone Tiny 01
421 --------------------
422
423 If you are using Flying Stone Tiny 01, you need a SWD writer.
424
425 OpenOCD 0.9 now supports ST-Link/V2.  We can use it:
426
427   $ openocd -f interface/stlink-v2.cfg -f target/stm32f1x_stlink.cfg
428
429
430
431 STBee
432 -----
433
434 Reset the board with "USER" switch pushed.  Type following to write
435 to flash:
436
437   # cd ../tool
438   # ./dfuse.py ../src/build/gnuk.hex
439
440 Then, reset the board.
441
442
443 How to protect flash ROM
444 ========================
445
446 Invoke your OpenOCD and type:
447
448   $ telnet localhost 4444
449   > reset halt
450   > stm32f1x lock 0
451   > reset
452   > shutdown
453
454 After power-off / power-on sequence, the contents of flash ROM cannot
455 be accessible from JTAG debugger.
456
457 Note that it would be still possible for some implementation of DfuSe
458 to access the contents.  If you want to protect, killing DfuSe and
459 accessing by JTAG debugger is recommended.
460
461
462 How to configure
463 ================
464
465 You need python and pyscard (python-pyscard package in Debian) or
466 PyUSB 0.4.3 (python-usb package in Debian).
467
468 (1) [pyscard] Stop scdaemon
469     [PyUSB] Stop the pcsc daemon.
470
471 If scdaemon is running, please kill it, or you will get "Smartcard
472 Exception" by "Sharing violation".
473
474   $ gpg-connect-agent "SCD KILLSCD" "SCD BYE" /bye
475
476 In case of PyUSB tool, you need to stop pcscd.
477
478   # /etc/init.d/pcscd stop
479
480
481 (2) [Optional] Write fixed serial number
482
483 If you use fixed serial number in the file 'GNUK_SERIAL_NUMBER', you can do:
484
485   $ EMAIL=<YOUR-EMAIL-ADDRESS> ../tool/gnuk_put_binary_usb.py -s ../GNUK_SERIAL_NUMBER
486   Writing serial number
487   ...
488
489 (3) [Optional] Write card holder certificate
490
491 If you have card holder certificate binary file, you can do:
492
493   $ ../tool/gnuk_put_binary_usb.py ../../<YOUR-CERTIFICATE>.bin
494   ../../<YOUR-CERTIFICATE>.bin: <LENGTH-OF-YOUR-CERTIFICATE>
495   Updating card holder certificate
496   ...
497
498
499 How to run
500 ==========
501
502 Debug enabled
503 -------------
504
505 If you compiled with --enable-debug option, Gnuk has two interfaces
506 (one is CCID/ICCD device and another is virtual COM port).  Open
507 virtual COM port by:
508
509   $ cu -l /dev/ttyACM0
510
511 and you will see debug output of Gnuk.
512
513
514 Testing Gnuk
515 ------------
516
517 Type following command to see Gnuk runs:
518
519   $ gpg --card-status
520
521
522 Besides, there is a functionality test under test/ directory.  See
523 test/README.
524
525
526 Personalize the Token, import keys, and change the password
527 -----------------------------------------------------------
528
529 You can personalize the token, putting your information like: Name,
530 Login name, Sex, Languages, URL.  To do so, GnuPG command is:
531
532   $ gpg --card-edit
533
534 Note that the factory setting of user password is "123456" and admin
535 password is "12345678" as the specification.
536
537 It is recommended to create your keys on your computer, and import
538 them to Gnuk Token.  After you create your keys (they must be 2048-bit
539 RSA), you can import them.
540
541 Gnuk supports key generation, but this feature is young and should be
542 considered experimental.
543
544 For detail, please see documentation under doc/.  You can see the HTML
545 version at: http://www.fsij.org/doc-gnuk/
546
547
548 How to debug
549 ============
550
551 We can use GDB.
552
553   $ arm-none-eabi-gdb gnuk.elf
554
555
556 Inside GDB, we can connect OpenOCD by:
557
558   (gdb) target remote localhost:3333
559
560
561 You can see the output of PCSCD:
562
563   # /etc/init.d/pcscd stop
564   # LIBCCID_ifdLogLevel=7 /usr/sbin/pcscd --debug --foreground
565
566
567 You can observe the traffic of USB using "usbmon".  See the file:
568 linux/Documentation/usb/usbmon.txt
569
570
571 Firmware update
572 ===============
573
574 See doc/note/firmware-update.
575
576
577 Git Repositories
578 ================
579
580 Please use: https://anonscm.debian.org/cgit/gnuk/gnuk/
581
582 You can get it by:
583  
584     $ git clone git://anonscm.debian.org/gnuk/gnuk/gnuk.git
585
586 It's also available at: www.gniibe.org
587 You can browse at: http://git.gniibe.org/gitweb?p=gnuk/gnuk.git;a=summary
588
589 I put Chopstx as a submodule of Git.  Please do this:
590
591   $ git submodule init
592   $ git submodule update
593
594 We have migrated from ChibiOS/RT to Chopstx in Gnuk 1.1.  If you have
595 old code of ChibiOS/RT, you need:
596
597     Edit .git/config to remove chibios reference
598     git rm --cached chibios
599
600
601 Information on the Web
602 ======================
603
604 Please visit: http://www.fsij.org/gnuk/
605
606 Please see the FST-01 support pages:
607
608     http://www.gniibe.org/category/fst-01.html
609
610 Please consider to join Gnuk-users mailing list:
611
612     https://lists.alioth.debian.org/mailman/listinfo/gnuk-users
613
614
615 Your Contributions
616 ==================
617
618 FSIJ welcomes your contributions.  Please assign your copyright
619 to FSIJ (if possible).
620
621
622 Foot note
623 ==========
624
625 * NUK(R) is a registered trademark owend by MAPA GmbH, Germany.
626 --