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