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