Extended capabilities change
[gnuk/gnuk.git] / README
1 Gnuk - An Implementation of USB Cryptographic Token for GnuPG
2
3                                                           Version 1.1.3
4                                                              2014-04-16
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.3, 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) and EdDSA with
17 EdDSA, but this feature is pretty much experimental, and it requires
18 development version of GnuPG with newest version of libgcrypt.  You
19 will not able to keep using EdDSA keys, as the key format is subject
20 to change.
21
22
23 What's Gnuk?
24 ============
25
26 Gnuk is an implementation of USB cryptographic token for GNU Privacy
27 Guard.  Gnuk supports OpenPGP card protocol version 2, and it runs on
28 STM32F103 processor.
29
30 I wish that Gnuk will be a developer's soother who uses GnuPG.  I have
31 been nervous of storing secret key(s) on usual secondary storage.
32 There is a solution with OpenPGP card, but it is not the choice for
33 me, as card reader is not common device.  With Gnuk, this issue will
34 be solved by a USB token.
35
36 Please look at the graphics of "gnuk.svg" for the software name.  My
37 son used to be with his NUK(R), always, everywhere.  Now, I am with a
38 USB Cryptographic Token by "Gnuk", always, everywhere.
39
40
41 FAQ
42 ===
43
44 Q0: How Gnuk USB Token is superior than other solutions (OpenPGP
45     card 2.0, GPF Crypto Stick, etc.) ?
46     http://www.g10code.de/p-card.html
47     http://www.privacyfoundation.de/crypto_stick/
48 A0: Good points of Gnuk are:
49     * If you have skill of electronics and like DIY, you can build
50       Gnuk Token cheaper (see Q8-A8).
51     * You can study Gnuk to modify and to enhance.  For example, you
52       can implement your own authentication method with some sensor
53       such as an acceleration sensor.
54     * It is "of Free Software"; Gnuk is distributed under GPLv3+,
55             "by Free Software"; Gnuk development requires only Free Software
56                                 (GNU Toolchain, Python, etc.), 
57             "for Free Software"; Gnuk supports GnuPG.
58
59 Q1: What kind of key algorithm is supported?
60 A1: Gnuk version 1.0 only supports 2048-bit RSA.
61     Development version of Gnuk (1.1.x) supports 256-bit ECDSA and EdDSA.
62
63 Q2: How long does it take for digital signing?
64 A2: It takes a second and a half or so. 
65
66 Q3: What's your recommendation for target board?
67 A3: Orthodox choice is Olimex STM32-H103.
68     If you have skill of electronics and like DIY, STM32 part of STM8S
69     Discovery Kit might be the best choice.
70     FST-01 (Flying Stone Tiny 01) is available for sale, and it is a
71     kind of the best choice, hopefully.
72
73 Q4: What's version of GnuPG are you using?
74 A4: In Debian GNU/Linux system, I use gnupg 1.4.12-7 and gnupg-agent
75     2.0.20-1.
76
77 Q5: What's version of pcscd and libccid are you using?
78 A5: I don't use them, pcscd and libccid are optional, you can use Gnuk
79     without them.
80     I tested pcscd 1.5.5-4 and libccid 1.3.11-2 which were in Debian
81     squeeze.
82
83 Q6: What kinds of hardware is required for development?
84 A6: You need a target board plus a JTAG/SWD debugger.  If you just
85     want to test Gnuk for target boards with DfuSe, JTAG debugger is
86     not the requirement.  Note that for real use, you need JTAG/SWD
87     debugger to enable flash ROM protection.
88
89 Q7: How much does it cost?
90 A7: Olimex STM32-H103 plus ARM-USB-TINY-H cost 70 Euro or so.
91
92 Q8: How much does it cost for DIY version?
93 A8: STM8S Discovery Kit costs 750 JPY (< $10 USD) only.  You can build
94     your own JTAG debugger using FTDI2232 module (1450 JPY), see:
95     http://www.fsij.org/gnuk/jtag_dongle_ftdi2232
96
97 Q9: I got an error like "gpg: selecting openpgp failed: ec=6.108", what's up?
98
99 A9: GnuPG's SCDaemon has problems for handling insertion/removal of
100     card/reader.  When your newly inserted token is not found by
101     GnuPG, try killing scdaemon and let it to be invoked again.  I do:
102
103          $ gpg-connect-agent "SCD KILLSCD" "SCD BYE" /bye
104
105     and confirm scdaemon doesn't exist, then,
106
107          $ gpg-connect-agent learn /bye
108
109 Qa: With GNOME 2, I can't use Gnuk Token for SSH.  How can we use it for SSH?
110 Aa: You need to deactivate seahorse-agent and gnome-keyring, but use
111     gpg-agant for the role of ssh-agent.  For gnome-keyring please do:
112
113       $ gconftool-2 --type bool --set /apps/gnome-keyring/daemon-components/ssh false
114
115 Qb: With GNOME 3, I can't use Gnuk Token at all.  Why?
116 Ab: That's because gnome-keyring-daemon interferes GnuPG.  Type:
117
118       $ gnome-session-properties
119
120     and at the tab of "Startup Programs", disable check buttons for
121     "GPG Password Agent" and "SSH Key Agent".
122
123 Qc: Do you know a good SWD debugger to connect FST-01 or something?
124 Ac: ST-Link/V2 is cheap one.  We have a tool/stlinkv2.py as flash ROM
125     writer program.
126
127
128 Release notes
129 =============
130
131 This is third experimental release in version 1.1 series of Gnuk.
132
133 While it is daily use by its developer, some newly introduced features
134 (including ECDSA/EdDSA, key generation and firmware upgrade) should be
135 considered experimental.  ECDSA/EdDSA is really experimental.  The
136 feature even requires manual edit of Makefile after 'configure'.
137 More, EdDSA is much experimental.  You won't be able to keep using
138 the EdDSA key, as it is subject to change.
139
140 Tested features are:
141
142         * Personalization of the card
143           * Changing Login name, URL, Name, Sex, Language, etc.
144         * Password handling (PW1, RC, PW3)
145         * Key import for three types:
146           * key for digital signing
147           * key for decryption
148           * key for authentication
149         * PSO: Digital Signature
150         * PSO: Decipher
151         * INTERNAL AUTHENTICATE
152         * Changing value of password status bytes (0x00C4): forcesig
153         * Verify with pin pad
154         * Modify with pin pad
155         * Card holder certificate (read)
156         * Removal of keys
157         * Key generation on device side
158         * Overriding key import
159
160 Original features of Gnuk, tested lightly:
161
162         * OpenPGP card serial number setup
163         * Card holder certificate (write by UPDATE BINARY)
164         * Upgrading with "EXTERNAL AUTHENTICATE" by reGNUal
165
166 It is known not-working well:
167
168         * It is known that the combination of libccid 1.4.1 (or newer)
169           with libusb 1.0.8 (or older) has a minor problem.  It is
170           rare but it is possible for USB communication to be failed,
171           because of a bug in libusb implementation.  Use libusbx
172           1.0.9 or newer, or don't use PC/SC, but use internal CCID
173           driver of GnuPG.
174
175
176 Targets
177 =======
178
179 We use Olimex STM32-H103 board and Flying Stone Tiny 01 (FST-01).  We
180 also use STM32 part of STM8S Discovery Kit.
181
182 With DfuSe support, STBee is also our targets.  But this target with
183 DfuSe is for experiment only, because it is impossible for DfuSe to
184 disable read from flash.  For real use, please consider killing DfuSe
185 and enabling read protection using JTAG debugger.
186
187 For PIN-pad support, I connect a consumer IR receive module to FST-01
188 and STM8S Discovery Kit, and use controller for TV.  PIN verification
189 is supported by this configuration.  Yes, it is not secure at all,
190 since it is very easy to monitor IR output of the controllers.  It is
191 just an experiment.  Note that hardware needed for this experiment is
192 only a consumer IR receive module which is as cheap as 50 JPY.
193
194 Note that you need pinpad support for GnuPG to use PIN-pad enabled
195 Gnuk.  The pinpad support for GnuPG is only available in version 2.
196
197
198 Souce code
199 ==========
200
201 Gnuk source code is under src/ directory.
202
203 Note that SHA-2 hash function implementation, src/sha256.c, is based
204 on the original implementation by Dr. Brian Gladman.  See:
205
206   http://gladman.plushost.co.uk/oldsite/cryptography_technology/sha/index.php
207
208
209 License
210 =======
211
212 It is distributed under GNU General Public Licence version 3 or later
213 (GPLv3+).  Please see src/COPYING.
214
215 Please note that it is distributed with external source code too.
216 Please read relevant licenses for external source code as well.
217
218 The author(s) of Gnuk expect users of Gnuk will be able to access the
219 source code of Gnuk, so that users can study the code and can modify
220 if needed.  This doesn't mean person who has a Gnuk Token should be
221 able to access everything on the Token, regardless of its protections.
222 Private keys, and other information should be protected properly.
223
224
225 External source code
226 ====================
227
228 Gnuk is distributed with external source code.
229
230 * chopstx/  -- Chopstx 0.03 (+ STBee support)
231
232   We use Chopstx as the kernel for Gnuk.
233
234   Chopstx is distributed under GPLv3+ (with a special exception).
235
236
237 * polarssl/  -- PolarSSL 1.2.10
238
239   Souce code taken from: http://polarssl.org/
240
241   We use PolarSSL for RSA computation, and AES encryption/decryption.
242
243   PolarSSL is distributed under GPLv2+.  We use PolarSSL under GPLv3
244   as our options.
245
246   The file include/polarssl/bn_mul.h is heavily modified for ARM
247   Cortex-M3.
248
249   The function rsa_private in polarssl/library/rsa.c is modified so
250   that it doesn't check T against N.  The function rsa_pkcs1_sign is
251   modified to avoid warnings in case of !POLARSSL_PKCS1_V21.
252
253   The functions rsa_pkcs1_verify and rsa_rsassa_pkcs1_v15_verify in
254   include/polarssl/rsa.h and polarssl/library/rsa.c are modified
255   (fixed) for last argument SIG, as the memory at SIG aren't modified
256   by those routines.
257
258   The constant POLARSSL_MPI_MAX_SIZE in include/polarssl/bignum.h is
259   modified for 2048-bit keys only Gnuk.
260
261   The function mpi_mul_hlp in library/bignum.c is modified for more
262   optimization for ARM Cortex-M3.  Functions mpi_montred, mpi_sub_hlp,
263   mpi_sub_abs, mpi_mul_mpi, mpi_montmul, and mpi_exp_mod are modified
264   to avoid side channel attacks.  Note that we don't use RSA-blinding
265   technique for Gnuk.  Function mpi_gen_prime and mpi_is_prime are
266   modified to use Fouque-Tibouchi method.  Function mpi_exp_mod is
267   modified to use new function mpi_montsqr for speed up.
268
269   The file library/aes.c is modified so that some constants can
270   go to .sys section.
271
272   The file include/polarssl/config.h are modified not to define
273   POLARSSL_HAVE_LONGLONG to avoid linking libgcc, to define
274   POLARSSL_AES_ROM_TABLES to have AES tables, not to define
275   POLARSSL_CIPHER_MODE_CTR, POLARSSL_FS_IO, POLARSSL_PKCS1_V21,
276   POLARSSL_SELF_TEST, and POLARSSL_PADLOCK_C, and only define
277   POLARSSL_GENPRIME when defined KEYGEN_SUPPORT.
278
279
280 USB vendor ID and product ID (USB device ID)
281 ============================================
282
283 When you have a vender ID and assign a product ID for Gnuk, edit the
284 file GNUK_USB_DEVICE_ID and add an entry for yours.  In this case,
285 please contact Niibe, so that it is listed to the file in the official
286 release of the source code.
287
288 When you are modifing Gnuk and installing the binary to device, you
289 should replace the vendor string and serial number to yours (in the
290 file GNUK_USB_DEVICE_ID and SERIALNO of the script of src/configure),
291 so that users can see it's not by original vendor, and it is modified
292 version.
293
294 FSIJ allows you to use USB device ID of FSIJ (234b:0000) for devices
295 with Gnuk under one of following conditions:
296
297   * For everyone for experimental purpose:
298
299     - You must not distribute a binary with FSIJ's USB device ID, but
300       must use the binary by yourself only for your experiment.  Note
301       that "Distributing binary" includes distributing a device which
302       holds the binary.
303
304   * For general individuals:
305
306     - You must use your Gnuk device with a card serial number which is
307       *not* by FSIJ.  Easy one would be a card serial number generated
308       by chip unique ID.
309
310   * For individuals with explicit permission from FSIJ.
311
312     - You should have an assigned card serial number by FSIJ,
313       please use that number for your device.
314       (There a file 'GNUK_SERIAL_NUMBER' in the official release.)
315
316 FSIJ could give companies or business entities "second source
317 manufacturer" license to use USB device ID of FSIJ for devices with
318 unmodified version of Gnuk, provided they support Free Software and
319 respect users' freedom for computing.  Please ask FSIJ for the
320 license.
321
322 Otherwise, companies which want to distribute Gnuk devices, please use
323 your own USB vendor ID and product ID.  Please replace vendor string
324 and possibly product string to yours, when you modify Gnuk.
325
326
327 Host Requirements
328 =================
329
330 For GNU/Linux, PC/SC service is an option, you can use GnuPG's
331 internal CCID driver instead.  If you chose using PC/SC service,
332 libccid version >= 1.3.11 is recommended for GNU/Linux.
333
334
335 How to compile
336 ==============
337
338 You need GNU toolchain and newlib for 'arm-none-eabi' target.
339
340 There is "gcc-arm-embedded" project.  See:
341
342     https://launchpad.net/gcc-arm-embedded/
343
344
345 Change directory to `src':
346
347   $ cd gnuk-VERSION/src
348
349 Then, run `configure':
350
351   $ ./configure --vidpid=<VID:PID>
352
353 Here, you need to specify USB vendor ID and product ID.  For FSIJ's,
354 it's: --vidpid=234b:0000 .  Please read section 'USB vendor ID and
355 product ID' above.
356
357 Type:
358
359   $ make
360
361 Then, we will have "gnuk.elf" under src/build directory.
362
363
364 How to install
365 ==============
366
367 Olimex STM32-H103 board
368 -----------------------
369
370 If you are using Olimex JTAG-Tiny, type following to invoke OpenOCD:
371
372   $ openocd -f interface/olimex-jtag-tiny.cfg -f board/olimex_stm32_h103.cfg
373
374 Then, with another terminal, type following to write "gnuk.elf" to Flash ROM:
375
376   $ telnet localhost 4444
377   > reset halt
378   > flash write_image erase gnuk.elf
379   > reset
380   > exit
381   $ 
382
383
384 Flying Stone Tiny 01
385 --------------------
386
387 If you are using Flying Stone Tiny 01, you need a SWD writer.  I am
388 using revision 946 of Simon Qian's Versaloon.
389
390     svn checkout -r 946 http://vsprog.googlecode.com/svn/trunk/
391
392 For OpenOCD, we need unofficial patch.
393
394 See the article of Versaloon Forum:
395
396     http://www.versaloon.com/bbs/viewtopic.php?p=16179
397
398
399 Type following to invoke OpenOCD:
400
401   $ openocd -f interface/vsllink.cfg -c "transport select swd" -c "swd_mode 2" -f target/stm32f1x.cfg
402
403 Then, with another terminal, type following to write "gnuk.elf" to Flash ROM:
404
405   $ telnet localhost 4444
406   > reset halt
407   > flash write_image erase gnuk.elf
408   > reset
409   > exit
410   $ 
411
412 OpenOCD 0.6.1 now supports ST-Link/V2.  We can use it:
413
414   $ openocd -f interface/stlink-v2.cfg -f target/stm32f1x_stlink.cfg
415
416 But it doesn't support option bytes handling (protection) yet.
417
418
419 STM8S Discovery Kit
420 -------------------
421
422 If you are using FTDI-2232D module and the connection is standard, type:
423
424   $ openocd -f interface/openocd-usb.cfg -f target/stm32f1x.cfg
425
426 Initially, the flash ROM of the chip is protected.  you need to do:
427
428   $ telnet localhost 4444
429   > reset halt
430   > stm32f1x unlock 0
431   > reset
432   > shutdown
433   $ 
434
435 and re-connect the board.  Note that power-off / power-on sequence is
436 required to reset flash ROM.
437
438 Then, invoke OpenOCD again and telnet to connect OpenCD and write
439 image as above example of Olimex STM32-H103.
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 Invoke your OpenOCD and type:
458
459   $ telnet localhost 4444
460   > reset halt
461   > stm32f1x lock 0
462   > reset
463   > shutdown
464
465 After power-off / power-on sequence, the contents of flash ROM cannot
466 be accessible from JTAG debugger.
467
468 Note that it would be still possible for some implementation of DfuSe
469 to access the contents.  If you want to protect, killing DfuSe and
470 accessing by JTAG debugger is recommended.
471
472
473 How to configure
474 ================
475
476 You need python and pyscard (python-pyscard package in Debian) or
477 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.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.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 test/ directory.  See
534 test/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: http://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
572 You can see the output of PCSCD:
573
574   # /etc/init.d/pcscd stop
575   # LIBCCID_ifdLogLevel=7 /usr/sbin/pcscd --debug --foreground
576
577
578 You can observe the traffic of USB using "usbmon".  See the file:
579 linux/Documentation/usb/usbmon.txt
580
581
582 Firmware update
583 ===============
584
585 See doc/note/firmware-update.
586
587
588 Git Repositories
589 ================
590
591 Please use: http://gitorious.org/gnuk
592
593 You can get it by:
594  
595     $ git clone git://gitorious.org/gnuk/gnuk.git
596
597 It's also available at: www.gniibe.org
598 You can browse at: http://www.gniibe.org/gitweb?p=gnuk.git;a=summary
599
600 I put Chopstx as a submodule of Git.  Please do this:
601
602   $ git submodule init
603   $ git submodule update
604
605 We have migrated from ChibiOS/RT to Chopstx.  If you have old code of
606 ChibiOS/RT, you need:
607
608     Edit .git/config to remove chibios reference
609     git rm --cached chibios
610
611
612 Information on the Web
613 ======================
614
615 Please visit: http://www.fsij.org/gnuk/
616
617
618 Your Contributions
619 ==================
620
621 FSIJ welcomes your contributions.  Please assign your copyright
622 to FSIJ (if possible).
623
624
625 Foot note
626 ==========
627 * NUK(R) is a registered trademark owend by MAPA GmbH, Germany.
628 --