d5cfacf7276ed3dbe0e35f60260347c6ddc47797
[gnuk/gnuk.git] / README
1 Gnuk - software for GnuPG USB Token
2
3                                                            Version 0.13
4                                                              2011-06-15
5                                                            Niibe Yutaka
6                                       Free Software Initiative of Japan
7
8 What's Gnuk?
9 ============
10
11 Gnuk is software implementation of a USB token for GNU Privacy Guard.
12 Gnuk supports OpenPGP card protocol version 2, and it runs on STM32
13 processor.
14
15 I wish that Gnuk will be a developer's soother who uses GnuPG.  I have
16 been nervous of storing secret key(s) on usual secondary storage.
17 While I want to work at different places, but it is not the choice for
18 me to bring a card reader all the time.  With Gnuk, this issue will be
19 solved by a USB token which is small enough.
20
21 Please look at the graphics of "gnuk.svg" for the software name.  My
22 son used to be with his NUK(R), always, everywhere.  I am with a USB
23 Token by "Gnuk", always, everywhere.
24
25
26 FAQ
27 ===
28
29 Q0: How Gnuk USB Token is superior than other solutions (OpenPGP
30     card 2.0, GPF Crypto Stick, etc) ?
31     http://www.g10code.de/p-card.html
32     http://www.privacyfoundation.de/crypto_stick/
33 A0: IMRHO, not quite.  There is no ready-to-use out-of-box product.
34     (It is welcome for me that some vendor will manufacture Gnuk USB
35      Token.  Even I can help design of hardware, if needed.)
36     Good points are:
37     * If you have skill of electronics and like DIY, you can build
38       Gnuk Token cheaper (see Q8-A8).
39     * You can study Gnuk to modify and to enhance.  For example, you
40       can implement your own authentication method with some sensor
41       such as acceleration sensor.
42     * It is "of Free Software"; Gnuk is distributed under GPLv3+,
43             "by Free Software"; Gnuk development requires only Free Software
44                                 (GNU Toolchain, Python, etc.), 
45             "for Free Software"; Gnuk supports GnuPG.
46
47 Q1: What kind of key algorithm is supported?
48 A1: Gnuk only supports 2048-bit RSA.
49
50 Q2: How long does it take for digital signing?
51 A2: It takes a second and a half or so. 
52
53 Q3: What's your recommendation for target board?
54 A3: Orthodox choice is Olimex STM32-H103.
55     If you have skill of electronics and like DIY, STM32 part of STM8S
56     Discovery Kit might be the best choice.
57
58 Q4: What's version of GnuPG are you using?
59 A4: In Debian GNU/Linux system, I use gnupg 1.4.11-3 and gnupg-agent
60     2.0.14-2 (in sid).  With older versions, you can only sign with SHA1.
61     See: http://www.fsij.org/gnuk/gnupg2-fixes-needed
62
63 Q5: What's version of pcscd and libccid are you using?
64 A5: In Debian GNU/Linux system, I use pcscd 1.5.5-4 and libccid 1.3.11-2,
65     which is in squeeze.  Note that you need to edit /etc/libccid_Info.plist
66     when using libccid (< 1.4.1).
67
68 Q6: What kinds of hardware is required for development?
69 A6: You need a target board plus a JTAG debugger.  If you just want to
70     test Gnuk for target boards with DfuSe, JTAG debugger is not
71     the requirement.  Note that for real use, you need JTAG debugger
72     to enable flash ROM protection.
73
74 Q7: How much does it cost?
75 A7: Olimex STM32-H103 plus ARM-USB-TINY-H cost 70 Euro or so.
76
77 Q8: How much does it cost for DIY version?
78 A8: STM8S Discovery Kit costs 750 JPY (< $10 USD) only.  You can build
79     your own JTAG debugger using FTDI2232 module (1450 JPY), see:
80     http://www.fsij.org/gnuk/jtag_dongle_ftdi2232
81
82 Q9: I got an error like "gpg: selecting openpgp failed: ec=6.108", what's up?
83 A9: GnuPG's SCDaemon has problems for handling insertion/removal of
84     card/reader (problems are fixed in trunk).  When your newly
85     inserted token is not found by GnuPG, try killing scdaemon and let
86     it to be invoked again.  I do:
87       $ killall -9 scdaemon
88     and confirm scdaemon doesn't exist, then,
89       $ gpg-connect-agent learn /bye
90
91
92 Release notes
93 =============
94
95 This is fourteenth release of Gnuk.  While it works well for specific
96 usages and it is considered stable, it is still somewhat experimental.
97
98 Note that you need to write random bits after installation of gnuk
99 executable to the chip.  This procedure is required to share a single
100 executable among multiple devices.
101
102 Tested features are:
103
104         * Personalization of the card
105           * Changing Login name, URL, Name, Sex, Language, etc.
106         * Password handling (PW1, RC, PW3)
107         * Key import for three types:
108           * key for digital signing
109           * key for decryption
110           * key for authentication
111         * PSO: Digital Signature
112         * PSO: Decipher
113         * INTERNAL AUTHENTICATE
114         * Changing value of password status bytes (0x00C4): forcesig
115         * Verify with pin pad
116         * Modify with pin pad
117
118 It is known not-working well:
119
120         * For some version of kernel and libccid, --enable-debug can't
121           work well.  Please disable DEBUG option if it doesn't work well.
122
123         * Card holder certificate
124           It is implemented in Gnuk side.  But its size matters (>
125           1KB).  GnuPG cannot handle a data object of large size with
126           PC/SC backend.  Specifically, handle_transmit function in
127           pcsc-wrapper.c uses the buffer of size 1024-byte.
128
129 Not supported feature(s):
130
131         * Overriding key import.  You need to remove all keys first.
132         * Key generation
133
134
135 Targets
136 =======
137
138 We use Olimex STM32-H103 board.  We also use STM32 part of STM8S
139 Discovery Kit.
140
141 With DfuSe support, CQ STARM, STBee, and STBee Mini are also our
142 targets.  But those targets with DfuSe are basically not for normal
143 use but for experiments, because it would be impossible for DfuSe to
144 disable read from flash.  For real use, please consider killing DfuSe
145 and enable read protection using JTAG debugger.
146
147 I think that it could run on Olimex STM32-P103, or other boards with
148 STM32F103.  Besides, we are porting it to STM32 Primer 2.
149
150 For PIN-pad support, I connect a consumer IR receive module to STBee
151 Mini and STM8S Discovery Kit, and use controller for TV.  PIN
152 verification is supported by this configuration.  Yes, it is not
153 secure at all, since it is very easy to monitor IR output of the
154 controllers.  It is just an experiment.  Note that hardware needed for
155 this experiment is only a consumer IR receive module which is as cheap
156 as 50 JPY.
157
158 Another PIN-pad support is connecting rotary encoder, push switch and
159 7-segment LED display.  Both of PIN verification and PIN modification
160 are supported for this circuit extension.
161
162
163 Souce code
164 ==========
165
166 Gnuk source code is under src/ directory.
167
168
169 License
170 =======
171
172 It is distributed under GNU General Public Licence version 3 or later
173 (GPLv3+).  Please see src/COPYING.
174
175 Please note that it is distributed with external source code too.
176 Please read relevant licenses for external source code, too.
177
178 The author(s) of Gnuk expect users of Gnuk will be able to access the
179 source code of Gnuk, so that users can study the code and can modify
180 if needed.  This doesn't mean person who has a USB Token by Gnuk
181 should be able to acess everything on the Token, regardless of its
182 protections.  Private keys, random bytes, and other information should
183 be protected properly.
184
185
186 External source code
187 ====================
188
189 Gnuk is distributed with external source code.
190
191 * ChibiOS_2.0.8/  -- ChibiOS/RT 2.0.8
192
193   Taken from http://chibios.sourceforge.net/
194   Note that CRLF is converted to LF in this repository.
195   We use ChibiOS/RT as the kernel for Gnuk.
196
197 * polarssl-0.14.0/  -- PolarSSL 0.14.0
198
199   Taken from http://polarssl.org/
200   We use PolarSSL for RSA computation, AES encryption/decryption
201   and SHA-1 computation.
202
203   The file include/polarssl/bn_mul.h is heavily modified for ARM
204   Cortex-M3.
205
206 * STM32_USB-FS-Device_Driver/ -- a part of USB-FS-Device_Lib
207 * Virtual_COM_Port/ -- a part of USB-FS-Device_Lib
208
209   STM32F10x USB Full Speed Device Library (USB-FS-Device_Lib)
210   is a STM32F10x library for USB functionality.
211
212   I took Libraries/STM32_USB-FS-Device_Driver and 
213   Project/Virtual_COM_Port in STM32_USB-FS-Device_Lib distribution.
214   See http://www.st.com/ for detail.
215
216
217 Host Requirements
218 =================
219
220 For GNU/Linux, libccid version >= 1.3.11 is required.
221 libccid version == 1.3.9 is known not working well by the issue [r4235].
222
223 I think that it should not be requirment but the kernel version of my use is:
224 Linux version 2.6.32-5-686 (Debian 2.6.32-18) (ben@decadent.org.uk) (gcc version 4.3.5 (Debian 4.3.5-2) ) #1 SMP Sat Jul 24 02:27:10 UTC 2010
225
226 Linux 2.6.30 is known *NOT* working well with DEBUG option.
227 Linux 2.6.24 is known working well with DEBUG option.
228
229
230 How to compile
231 ==============
232
233 You need GNU toolchain and newlib for 'arm-none-eabi' target.
234
235 See http://github.com/uwehermann/summon-arm-toolchain/ for preparation
236 of GNU Toolchain for 'arm-none-eabi' target.
237
238 Change directory to `src':
239
240   $ cd gnuk-VERSION/src
241
242 Then, run `configure':
243
244   $ ./configure
245
246 Type:
247
248   $ make
249
250 Then, we will have "gnuk.elf".
251
252
253 How to install
254 ==============
255
256 Olimex STM32-H103 board
257 -----------------------
258
259 If you are using Olimex JTAG-Tiny, type following to invoke OpenOCD:
260
261   $ openocd -f interface/olimex-jtag-tiny.cfg -f board/olimex_stm32_h103.cfg
262
263 Then, with another terminal, type following to write "gnuk.elf" to Flash ROM:
264
265   $ telnet localhost 4444
266   > reset halt
267   > flash write_image erase gnuk.elf
268   > reset
269   > exit
270   $ 
271
272
273 STM8S Discovery Kit
274 -------------------
275
276 If you are using FTDI-2232D module and the connection is standard, type:
277
278   $ openocd -f interface/openocd-usb.cfg -f target/stm32.cfg
279
280 Initially, the flash ROM of the chip is protected.  you need to do:
281
282   $ telnet localhost 4444
283   > reset halt
284   > stm32x unlock 0
285   > reset
286   > shutdown
287   $ 
288
289 and re-connect the board.  Note that power-off / power-on sequence is
290 required to reset flash ROM.
291
292 Then, invoke OpenOCD again and telnet to connect OpenCD and write
293 image as above example of Olimex STM32-H103.
294
295
296 CQ STARM
297 --------
298
299 Put jumper for J6 to enable DfuSe.  Connecting the board, and type:
300
301   # cd ../tool
302   # ./dfuse.py ../src/gnuk.hex
303
304 Then, remove the jumper and reset the board.
305
306
307 STBee and STBee Mini
308 --------------------
309
310 Reset the board with "USER" switch pushed.  Type following to write
311 to flash:
312
313   # cd ../tool
314   # ./dfuse.py ../src/gnuk.hex
315
316 Then, reset the board.
317
318
319 How to protect flash ROM
320 ========================
321
322 Invoke your OpenOCD and type:
323
324   $ telnet localhost 4444
325   > reset halt
326   > stm32x lock 0
327   > reset
328   > shutdown
329
330 After power-off / power-on sequence, the contents of flash ROM cannot
331 be accessible from JTAG debugger.
332
333 Note that it would be still possible for some implementation of DfuSe
334 to access the contents.  If you want to protect, killing DfuSe and
335 accessing by JTAG debugger is recommended.
336
337
338 How to configure
339 ================
340
341 You need python and pyscard (python-pyscard package in Debian) or
342 PyUSB (python-usb package in Debian).
343
344 (1) In the 'src' directory, type
345
346   $ make random_bits
347
348 In this process, it takes time for the command of
349
350    dd if=/dev/random bs=1 of=random_bits count=1024
351
352 Don't just wait, but do some other works on your PC.
353 /dev/random needs entropy to finish.
354
355
356 (2) [pyscard] Stop scdaemon
357     [PyUSB] Stop the pcsc daemon.
358
359 If scdaemon is running, please kill it, or you will get "Smartcard
360 Exception" by "Sharing violation".
361
362   $ killall -9 scdaemon
363
364 In case of PyUSB tool, you need to stop pcscd.
365
366   # /etc/init.d/pcscd stop
367
368
369 (3) Write the random bits to the device
370
371 Connect your board to USB port of your PC.  And invoke gnuk_put_binary.py:
372
373   $ ../tool/gnuk_put_binary.py -r random_bits
374   random_bits: 1024
375   Updating random bits
376   ...
377
378
379 (4) [Optional] Write fixed serial number
380
381 If you use fixed serial number in the file 'GNUK_SERIAL_NUMBER', you can do:
382
383   $ EMAIL=<YOUR-EMAIL-ADDRESS> ../tool/gnuk_put_binary.py -s ../GNUK_SERIAL_NUMBER
384   Writing serial number
385   ...
386
387 (5) [Optional] Write card holder certificate
388
389 If you have card holder certificate binary file, you can do:
390
391   $ ../tool/gnuk_put_binary.py ../../<YOUR-CERTIFICATE>.bin
392   ../../<YOUR-CERTIFICATE>.bin: <LENGTH-OF-YOUR-CERTIFICATE>
393   Updating card holder certificate
394   ...
395
396
397 How to run
398 ==========
399
400 Debug enabled
401 -------------
402
403 If you compiled with --enable-debug option, Gnuk has two interfaces
404 (one is CCID/ICCD device and another is virtual COM port).  Open
405 virtual COM port by:
406
407   $ cu -l /dev/ttyACM0
408
409 and you will see debug output of Gnuk.
410
411
412 Libccid fix needed
413 ------------------
414
415 For libccid (< 1.4.1), we need following change:
416
417 --- /etc/libccid_Info.plist.dpkg-dist   2009-07-29 06:50:20.000000000 +0900
418 +++ /etc/libccid_Info.plist     2010-09-05 09:09:49.000000000 +0900
419 @@ -104,6 +104,7 @@
420  
421         <key>ifdVendorID</key>
422         <array>
423 +               <string>0x234B</string>
424                 <string>0x08E6</string>
425                 <string>0x08E6</string>
426                 <string>0x08E6</string>
427 @@ -237,6 +238,7 @@
428  
429         <key>ifdProductID</key>
430         <array>
431 +               <string>0x0000</string>
432                 <string>0x2202</string>
433                 <string>0x3437</string>
434                 <string>0x3438</string>
435 @@ -370,6 +372,7 @@
436  
437         <key>ifdFriendlyName</key>
438         <array>
439 +               <string>FSIJ USB Token</string>
440                 <string>Gemplus Gem e-Seal Pro</string>
441                 <string>Gemplus GemPC Twin</string>
442                 <string>Gemplus GemPC Key</string>
443 ------------------
444
445 This entry has been added into libccid 1.4.1 already ([r5425]).
446
447
448 Testing Gnuk
449 ------------
450
451 Try following to see Gnuk runs:
452
453   $ gpg --card-status
454
455
456 Personalize the Token and import keys
457 -------------------------------------
458
459 You can personalize the token, putting your information like: Name,
460 Login name, Sex, Languages, URL, etc., and password.  To do so, GnuPG
461 command is:
462
463   $ gpg --card-edit
464
465 Note that the factory setting of user password is "123456" and admin
466 password is "12345678" as the specification.
467
468 No, Gnuk doesn't support key generation.  You need to create your
469 keys on your computer, and import them to Gnuk Token.  After you create
470 your keys (they must be 2048-bit RSA), you can import them.
471
472 For detail, please see doc/DEMO and doc/DEMO-2.
473
474 Note that it make sense to preserve your keys on your computer so that
475 you can import the keys (again) to (possibly another) Gnuk Token.  In
476 this case, you can use GnuPG's option to specify the home directory by
477 --homedir.
478
479 After creating keys by:
480
481   $ gpg --gen-key
482   ...
483
484 Copy directory which contains your secret keys to new directory named
485 <gpgdir-with-your-secret-keys>:
486
487   $ cp -pa $HOME/.gnupg <gpgdir-with-your-secret-keys>
488
489 Then, import keys by:
490
491   $ gpg --edit-key <YOUR-KEYID>
492
493 While your $HOME/.gnupg now doesn't have your secret keys after
494 import, <gpgdir-with-your-secret-keys> still has them.  You can again
495 import them by:
496
497   $ gpg --homedir=<gpgdir-with-your-secret-keys> --edit-key <YOUR-KEYID>
498
499 Note that you *should not* save changes this time to preserve keys
500 on your computer.  The session goes like this:
501
502   gpg> quit
503   Save changes? (y/N) n
504   Quit without saving? (y/N) y
505
506
507
508 How to debug
509 ============
510
511 We can use GDB.
512
513   $ arm-none-eabi-gdb gnuk.elf
514
515
516 Inside GDB, we can connect OpenOCD by:
517
518   (gdb) target remote localhost:3333
519
520
521 You can see the output of PCSCD:
522
523   # /etc/init.d/pcscd stop
524   # LIBCCID_ifdLogLevel=7 /usr/sbin/pcscd --debug --foreground
525
526
527 You can observe the traffic of USB using "usbmon".  See the file:
528 linux/Documentation/usb/usbmon.txt
529
530
531 Read-only Git Repository
532 ========================
533
534 You can browse at http://www.gniibe.org/gitweb?p=gnuk.git;a=summary
535
536 You can get it by:
537
538   $ git clone git://www.gniibe.org/gnuk.git/
539
540 or
541
542   $ git clone http://www.gniibe.org/git/gnuk.git/
543
544
545
546 Information on the Web
547 ======================
548
549 Please visit: http://www.fsij.org/gnuk/
550
551
552 Your Contributions
553 ==================
554
555 FSIJ welcomes your contributions.  Please assign your copyright
556 to FSIJ (if possible).
557
558
559 Foot note
560 ==========
561 * NUK(R) is a registered trademark owend by MAPA GmbH, Germany.
562 --