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