Version 0.10
[gnuk/gnuk.git] / README
1 Gnuk - software for GPG USB Token
2
3                                                            Version 0.10
4                                                              2011-02-10
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 eleventh release of Gnuk.  While it works well for specific
30 usages, it is still experimental.  Note that you need to write random
31 bits after installation of gnuk executable to the chip from this
32 release.  This procedure is required to share a single executable
33 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 random_bits: 1024
305
306 (4) [Optional] Write fixed serial number
307
308 If you use fixed serial number in the file 'GNUK_SERIAL_NUMBER', you can do:
309
310   # EMAIL=<YOUR-EMAIL-ADDRESS> ../tool/gnuk_put_binary.py -s ../GNUK_SERIAL_NUMBER 
311
312 (5) [Optional] Write card holder certificate
313
314 If you have card holder certificate binary file, you can do:
315
316   # ../tool/gnuk_put_binary.py ../../<YOUR-CERTIFICATE>.bin 
317
318
319 How to run
320 ==========
321
322 Debug enabled
323 -------------
324
325 If you compiled with --enable-debug option, Gnuk has two interfaces
326 (one is CCID/ICCD device and another is virtual COM port).  Open
327 virtual COM port by:
328
329   $ cu -l /dev/ttyACM0
330
331 and you will see debug output of Gnuk.
332
333
334 Libccid fix needed
335 ------------------
336
337 For libccid (< 1.4.1), we need following change:
338
339 --- /etc/libccid_Info.plist.dpkg-dist   2009-07-29 06:50:20.000000000 +0900
340 +++ /etc/libccid_Info.plist     2010-09-05 09:09:49.000000000 +0900
341 @@ -104,6 +104,7 @@
342  
343         <key>ifdVendorID</key>
344         <array>
345 +               <string>0x234B</string>
346                 <string>0x08E6</string>
347                 <string>0x08E6</string>
348                 <string>0x08E6</string>
349 @@ -237,6 +238,7 @@
350  
351         <key>ifdProductID</key>
352         <array>
353 +               <string>0x0000</string>
354                 <string>0x2202</string>
355                 <string>0x3437</string>
356                 <string>0x3438</string>
357 @@ -370,6 +372,7 @@
358  
359         <key>ifdFriendlyName</key>
360         <array>
361 +               <string>FSIJ USB Token</string>
362                 <string>Gemplus Gem e-Seal Pro</string>
363                 <string>Gemplus GemPC Twin</string>
364                 <string>Gemplus GemPC Key</string>
365 ------------------
366
367 This entry has been added into libccid 1.4.1 already ([r5425]).
368
369
370 Testing Gnuk
371 ------------
372
373 Try following to see Gnuk runs:
374
375   $ gpg --card-status
376
377
378 For more, see doc/DEMO.
379
380
381
382 How to debug
383 ============
384
385 We can use GDB.
386
387   $ arm-none-eabi-gdb gnuk.elf
388
389
390 Inside GDB, we can connect OpenOCD by:
391
392   (gdb) target remote localhost:3333
393
394
395 You can see the output of PCSCD:
396
397   # /etc/init.d/pcscd stop
398   # LIBCCID_ifdLogLevel=7 /usr/sbin/pcscd --debug --foreground
399
400
401 You can observe the traffic of USB using "usbmon".  See the file:
402 linux/Documentation/usb/usbmon.txt
403
404
405 Read-only Git Repository
406 ========================
407
408 You can get it by:
409
410   $ git clone http://www.gniibe.org/git/gnuk.git/
411
412
413 Information on the Web
414 ======================
415
416 Please see: http://www.fsij.org/gnuk/
417
418
419 Your Contributions
420 ==================
421
422 FSIJ welcomes your contributions.  Please assign your copyright
423 to FSIJ (if possible).
424
425
426 Foot note
427 ==========
428 * NUK(R) is a registered trademark owend by MAPA GmbH, Germany.
429 --