added FAQ section
[gnuk/gnuk.git] / README
1 Gnuk - software for GPG USB Token
2
3                                                            Version 0.11
4                                                              2011-04-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 will be with a
23 USB Token by "Gnuk" everywhere.
24
25
26 FAQ
27 ===
28
29 Q1: What's kind of key algorithm is supported?
30 A1: Gnuk only supports 2048-bit RSA.
31
32 Q2: How long does it take for digital signing?
33 A2: It takes two seconds or so. 
34
35 Q3: What's your recommendation for target board?
36 A3: Orthodox choice is Olimex STM32-H103.
37     If you have skill of electronics and like DIY, STM32 part of STM8S
38     Discovery Kit might be the best choice.
39
40 Q4: What's version of GnuPG are you using?
41 A4: In Debian GNU/Linux system, I use GnuPG 2.0.14-2 (in sid).
42
43 Q5: What's version of pcscd and libccid are you using?
44 A5: In Debian GNU/Linux system, I use pcscd 1.5.5-4 and libccid 1.3.11-2,
45     which is in squeeze.  Note that you need to edit /etc/libccid_Info.plist
46     when using libccid (< 1.4.1).
47
48 Q6: What kinds of hardware is required for development?
49 A6: You need a target board plus JTAG debugger.  If you just want to
50     test Gnuk for target boards with DfuSe, JTAG debugger is not
51     the requirement.  Note that for real use, you need JTAG debugger
52     to enable flash ROM protection.
53
54
55 Release notes
56 =============
57
58 This is twelfth release of Gnuk.  While it works well for specific
59 usages and it is considered stable, it is still somewhat experimental.
60 Note that you need to write random bits after installation of gnuk
61 executable to the chip.  This procedure is required to share a single
62 executable among multiple devices.
63
64 Tested features are:
65
66         * Personalization of the card
67
68           * Changing Login name, URL, Name, Sex, Language, etc.
69
70         * Password handling (PW1, RC, PW3)
71
72         * Key import for three types:
73
74           * key for digital signing
75
76           * key for decryption
77
78           * key for authentication
79
80         * PSO: Digital Signature
81
82         * PSO: Decipher
83
84         * INTERNAL AUTHENTICATE
85
86         * Changing value of password status bytes (0x00C4)
87
88         * Verify with pin pad
89
90         * Modify with pin pad
91
92 It is known not-working well:
93
94         * For some version of kernel and libccid, --enable-debug can't
95           work well.  Please disable DEBUG option if it doesn't work well.
96
97         * Card holder certificate
98           It is implemented in Gnuk side.  But its size matters (>
99           1KB).  GnuPG cannot handle a data object of large size with
100           PC/SC backend.  Specifically, handle_transmit function in
101           pcsc-wrapper.c uses the buffer of size 1024-byte.
102
103 Not supported feature(s):
104
105         * Overriding key import.  You need to remove all keys first.
106
107         * Key generation
108
109
110 Targets
111 =======
112
113 We use Olimex STM32-H103 board.  We also use STM32 part of STM8S
114 Discovery Kit.
115
116 With DfuSe support, CQ STARM, STBee, and STBee Mini are also our
117 targets.  But those targets with DfuSe are basically not for normal
118 use but for experiments, because it would be impossible for DfuSe to
119 disable read from flash.  For real use, please consider killing DfuSe
120 and enable read protection using JTAG debugger.
121
122 I think that it could run on Olimex STM32-P103, or other boards with
123 STM32F103.  Besides, we are porting it to STM32 Primer 2.
124
125 For PIN-pad support, I connect a consumer IR receive module to STBee
126 Mini and STM8S Discovery Kit, and use controller for TV.  PIN
127 verification is supported by this configuration.  Yes, it is not
128 secure at all, since it is very easy to monitor IR output of the
129 controllers.  It is just an experiment.  Note that hardware needed for
130 this experiment is only a consumer IR receive module which is as cheap
131 as 50 JPY.
132
133 Another PIN-pad support is connecting rotary encoder, push switch and
134 7-segment LED display.  Both of PIN verification and PIN modification
135 are supported for this circuit extension.
136
137
138 Souce code
139 ==========
140
141 Gnuk source code is under src/ directory.
142
143
144 License
145 =======
146
147 It is distributed under GNU General Public Licence version 3 or later
148 (GPLv3+).  Please see src/COPYING.
149
150 Please note that it is distributed with external source code too.
151 Please read relevant licenses for external source code, too.
152
153 The author(s) of Gnuk expect users of Gnuk will be able to access the
154 source code of Gnuk, so that users can study the code and can modify
155 if needed.  This doesn't mean person who has a USB Token by Gnuk
156 should be able to acess everything on the Token, regardless of its
157 protections.  Private keys, random bytes, and other information should
158 be protected properly.
159
160
161 External source code
162 ====================
163
164 Gnuk is distributed with external source code.
165
166 * ChibiOS_2.0.8/  -- ChibiOS/RT 2.0.8
167
168   Taken from http://chibios.sourceforge.net/
169   Note that CRLF is converted to LF in this repository.
170   We use ChibiOS/RT as the kernel for Gnuk.
171
172 * polarssl-0.14.0/  -- PolarSSL 0.14.0
173
174   Taken from http://polarssl.org/
175   We use PolarSSL for RSA computation, AES encryption/decryption
176   and SHA-1 computation.
177
178 * STM32_USB-FS-Device_Driver/ -- a part of USB-FS-Device_Lib
179 * Virtual_COM_Port/ -- a part of USB-FS-Device_Lib
180
181   STM32F10x USB Full Speed Device Library (USB-FS-Device_Lib)
182   is a STM32F10x library for USB functionality.
183
184   I took Libraries/STM32_USB-FS-Device_Driver and 
185   Project/Virtual_COM_Port in STM32_USB-FS-Device_Lib distribution.
186   See http://www.st.com/ for detail.
187
188
189 Host Requirements
190 =================
191
192 For GNU/Linux, libccid version >= 1.3.11 is required.
193 libccid version == 1.3.9 is known not working well by the issue [r4235].
194
195 I think that it should not be requirment but the kernel version of my use is:
196 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
197
198 Linux 2.6.30 is known *NOT* working well with DEBUG option.
199 Linux 2.6.24 is known working well with DEBUG option.
200
201
202 How to compile
203 ==============
204
205 You need GNU toolchain and newlib for 'arm-none-eabi' target.
206
207 See http://github.com/esden/summon-arm-toolchain/ for preparation of
208 GNU Toolchain for 'arm-none-eabi' target.
209
210 Change directory to `src':
211
212   $ cd gnuk-VERSION/src
213
214 Then, run `configure':
215
216   $ ./configure
217
218 Type:
219
220   $ make
221
222 Then, we will have "gnuk.elf".
223
224
225 How to install
226 ==============
227
228 Olimex STM32-H103 board
229 -----------------------
230
231 If you are using Olimex JTAG-Tiny, type following to invoke OpenOCD:
232
233   $ openocd -f interface/olimex-jtag-tiny.cfg -f board/olimex_stm32_h103.cfg
234
235 Then, with another terminal, type following to write "gnuk.elf" to Flash ROM:
236
237   $ telnet localhost 4444
238   > reset halt
239   > flash write_image erase gnuk.elf
240   > reset
241   > exit
242   $ 
243
244
245 STM8S Discovery Kit
246 -------------------
247
248 If you are using FTDI-2232D module and the connection is standard, type:
249
250   $ openocd -f interface/openocd-usb.cfg -f target/stm32.cfg
251
252 Initially, the flash ROM of the chip is protected.  you need to do:
253
254   $ telnet localhost 4444
255   > reset halt
256   > stm32x unlock 0
257   > reset
258   > shutdown
259   $ 
260
261 and re-connect the board.  Note that power-off / power-on sequence is
262 required to reset flash ROM.
263
264 Then, invoke OpenOCD again and telnet to connect OpenCD and write
265 image as above example of Olimex STM32-H103.
266
267
268 CQ STARM
269 --------
270
271 Put jumper for J6 to enable DfuSe.  Connecting the board, and type:
272
273   # cd ../tool
274   # ./dfuse.py ../src/gnuk.hex
275
276 Then, remove the jumper and reset the board.
277
278
279 STBee and STBee Mini
280 --------------------
281
282 Reset the board with "USER" switch pushed.  Type following to write
283 to flash:
284
285   # cd ../tool
286   # ./dfuse.py ../src/gnuk.hex
287
288 Then, reset the board.
289
290
291 How to protect flash ROM
292 ========================
293
294 Invoke your OpenOCD and type:
295
296   $ telnet localhost 4444
297   > reset halt
298   > stm32x lock 0
299   > reset
300   > shutdown
301
302 After power-off / power-on sequence, the contents of flash ROM cannot
303 be accessible from JTAG debugger.
304
305 Note that it would be still possible for some implementation of DfuSe
306 to access the contents.  If you want to protect, killing DfuSe and
307 accessing by JTAG debugger is recommended.
308
309
310 How to configure
311 ================
312
313 You need python and PyUSB (python-usb package in Debian).
314
315 (1) In the 'src' directory, type
316
317   $ make random_bits
318
319 In this process, it takes time for the command of
320
321    dd if=/dev/random bs=1 of=random_bits count=1024
322
323 Don't just wait, but do some other works on your PC.
324 /dev/random needs entropy to finish.
325
326 (2) Stop the pcsc daemon.
327
328   # /etc/init.d/pcscd stop
329
330 (3) Write the random bits to the device
331
332 Connect your board to USB port of your PC.  And invoke gnuk_put_binary.py:
333
334   # ../tool/gnuk_put_binary.py -r random_bits
335   random_bits: 1024
336   Updating random bits
337   ...
338
339 (4) [Optional] Write fixed serial number
340
341 If you use fixed serial number in the file 'GNUK_SERIAL_NUMBER', you can do:
342
343   # EMAIL=<YOUR-EMAIL-ADDRESS> ../tool/gnuk_put_binary.py -s ../GNUK_SERIAL_NUMBER 
344   Writing serial number
345   ...
346
347 (5) [Optional] Write card holder certificate
348
349 If you have card holder certificate binary file, you can do:
350
351   # ../tool/gnuk_put_binary.py ../../<YOUR-CERTIFICATE>.bin 
352   ../../<YOUR-CERTIFICATE>.bin: <LENGTH-OF-YOUR-CERTIFICATE>
353   Updating card holder certificate
354   ...
355
356
357 How to run
358 ==========
359
360 Debug enabled
361 -------------
362
363 If you compiled with --enable-debug option, Gnuk has two interfaces
364 (one is CCID/ICCD device and another is virtual COM port).  Open
365 virtual COM port by:
366
367   $ cu -l /dev/ttyACM0
368
369 and you will see debug output of Gnuk.
370
371
372 Libccid fix needed
373 ------------------
374
375 For libccid (< 1.4.1), we need following change:
376
377 --- /etc/libccid_Info.plist.dpkg-dist   2009-07-29 06:50:20.000000000 +0900
378 +++ /etc/libccid_Info.plist     2010-09-05 09:09:49.000000000 +0900
379 @@ -104,6 +104,7 @@
380  
381         <key>ifdVendorID</key>
382         <array>
383 +               <string>0x234B</string>
384                 <string>0x08E6</string>
385                 <string>0x08E6</string>
386                 <string>0x08E6</string>
387 @@ -237,6 +238,7 @@
388  
389         <key>ifdProductID</key>
390         <array>
391 +               <string>0x0000</string>
392                 <string>0x2202</string>
393                 <string>0x3437</string>
394                 <string>0x3438</string>
395 @@ -370,6 +372,7 @@
396  
397         <key>ifdFriendlyName</key>
398         <array>
399 +               <string>FSIJ USB Token</string>
400                 <string>Gemplus Gem e-Seal Pro</string>
401                 <string>Gemplus GemPC Twin</string>
402                 <string>Gemplus GemPC Key</string>
403 ------------------
404
405 This entry has been added into libccid 1.4.1 already ([r5425]).
406
407
408 Testing Gnuk
409 ------------
410
411 Try following to see Gnuk runs:
412
413   $ gpg --card-status
414
415
416 For more, see doc/DEMO.
417
418
419
420 How to debug
421 ============
422
423 We can use GDB.
424
425   $ arm-none-eabi-gdb gnuk.elf
426
427
428 Inside GDB, we can connect OpenOCD by:
429
430   (gdb) target remote localhost:3333
431
432
433 You can see the output of PCSCD:
434
435   # /etc/init.d/pcscd stop
436   # LIBCCID_ifdLogLevel=7 /usr/sbin/pcscd --debug --foreground
437
438
439 You can observe the traffic of USB using "usbmon".  See the file:
440 linux/Documentation/usb/usbmon.txt
441
442
443 Read-only Git Repository
444 ========================
445
446 You can get it by:
447
448   $ git clone http://www.gniibe.org/git/gnuk.git/
449
450
451 Information on the Web
452 ======================
453
454 Please see: http://www.fsij.org/gnuk/
455
456
457 Your Contributions
458 ==================
459
460 FSIJ welcomes your contributions.  Please assign your copyright
461 to FSIJ (if possible).
462
463
464 Foot note
465 ==========
466 * NUK(R) is a registered trademark owend by MAPA GmbH, Germany.
467 --