version 0.6
[gnuk/gnuk.git] / README
1 Gnuk - software for GPG USB Token
2
3                                                             Version 0.6
4                                                              2011-01-14
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 seventh release of Gnuk.  While it works well for specific
30 usages, it is still experimental.
31
32 Tested features are:
33
34         * Personalization of the card
35
36           * Changing Login name, URL, Name, Sex, Language, etc.
37
38         * Password handling (PW1, RC, PW3)
39
40         * Key import for three types:
41
42           * key for digital signing
43
44           * key for decryption
45
46           * key for authentication
47
48         * PSO: Digital Signature
49
50         * PSO: Decipher
51
52         * INTERNAL AUTHENTICATE
53
54         * Changing value of password status bytes (0x00C4)
55
56         * Verify with pin pad
57
58 It is known not-working well:
59
60         * For some version of kernel and libccid, --enable-debug can't
61           work well.  Please disable DEBUG option if it doesn't work well.
62
63 Not (yet) supported feature(s):
64
65         * card holder certificate (its size matters (> 1KiB?), if we support)
66
67 Not supported feature(s):
68
69         * Overriding key import.  You need to remove all keys first.
70
71
72 Targets
73 =======
74
75 We use Olimex STM32-H103 board.  We also use STM32 part of STM8S
76 Discovery Kit.
77
78 With DfuSe support, CQ STARM and STBee Mini are also our targets.  But
79 those targets with DfuSe are basically not for normal use but for
80 experiments, because it would be impossible for DfuSe to disable read
81 from flash.  For real use, please consider killing DfuSe and enable
82 read protect using JTAG debugger.
83
84 I think that it could run on Olimex STM32-P103, or STBee too.
85 Besides, we are porting it to STM32 Primer 2.
86
87 For PIN-pad support, I connect a consumer IR receive module to STBee
88 Mini and STM8S Discovery Kit, and use controller for TV.  Yes, it is
89 not secure totally, since it is very easy to monitor IR output of the
90 controllers.  It is experiment, and hardware needed for this
91 experiment is only a consumer IR receive module which is as cheap as
92 50 JPY.
93
94
95 Souce code
96 ==========
97
98 Gnuk source code is under src/ directory.
99
100
101 License
102 =======
103
104 It is distributed under GNU General Public Licence version 3 or later
105 (GPLv3+).  Please see src/COPYING.
106
107 Please note that it is distributed with external source code too.
108 Please read relevant licenses for external source code, too.
109
110 The author(s) of Gnuk expect users of Gnuk will be able to access the
111 source code of Gnuk.  This doesn't mean person who has a USB Token by
112 Gnuk should be able to acess everything on the Token, regardless of
113 its protections.  Private keys, random bytes, and other information
114 should be protected properly.
115
116
117 External source code
118 ====================
119
120 Gnuk is distributed with external source code.
121
122 * ChibiOS_2.0.8/  -- ChibiOS/RT 2.0.8
123
124   Taken from http://chibios.sourceforge.net/
125   Note that CRLF is converted to LF in this repository.
126   We use ChibiOS/RT as the kernel for Gnuk.
127
128 * polarssl-0.14.0/  -- PolarSSL 0.14.0
129
130   Taken from http://polarssl.org/
131   We use PolarSSL for RSA computation, AES encryption/decryption
132   and SHA-1 computation.
133
134 * STM32_USB-FS-Device_Driver/ -- a part of USB-FS-Device_Lib
135 * Virtual_COM_Port/ -- a part of USB-FS-Device_Lib
136
137   STM32F10x USB Full Speed Device Library (USB-FS-Device_Lib)
138   is a STM32F10x library for USB functionality.
139
140   I took Libraries/STM32_USB-FS-Device_Driver and 
141   Project/Virtual_COM_Port in STM32_USB-FS-Device_Lib distribution.
142   See http://www.st.com for detail.
143
144
145 Host Requirements
146 =================
147
148 For GNU/Linux, libccid version >= 1.3.11 is required.
149 libccid version == 1.3.9 is known not working well by the issue [r4235].
150
151 I think that it should not be requirment but the kernel version of my use is:
152 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
153
154 Linux 2.6.30 is known *NOT* working well with DEBUG option.
155 Linux 2.6.24 is known working well with DEBUG option.
156
157
158 How to compile
159 ==============
160
161 You need GNU toolchain and newlib for 'arm-none-eabi' target.
162
163 See http://github.com/esden/summon-arm-toolchain/ for preparation of
164 GNU Toolchain for 'arm-none-eabi' target.
165
166 Change directory to `src':
167
168   $ cd gnuk-VERSION/src
169
170 Then, run `configure':
171
172   $ ./configure
173
174 Type:
175
176   $ make
177
178 In the make process, it takes time for the command of
179
180    dd if=/dev/random bs=1 of=random_bits count=1024
181
182 Don't just wait, but do some other work on your PC.
183 /dev/random needs entropy to finish.
184
185 Then, we will have "gnuk.elf".
186
187
188 How to run
189 ==========
190
191 Olimex STM32-H103 board
192 -----------------------
193
194 If you are using Olimex JTAG-Tiny, type following to invoke OpenOCD:
195
196   $ openocd -f interface/olimex-jtag-tiny.cfg -f board/olimex_stm32_h103.cfg
197
198 Then, with another terminal, type following to write "gnuk.elf" to Flash ROM:
199
200   $ telnet localhost 4444
201   > reset halt
202   > flash write_image erase gnuk.elf
203   > reset
204   > exit
205   $ 
206
207
208 CQ STARM
209 --------
210
211 Put jumper for J6 to enable DfuSe.  Connecting the board, and type:
212
213   # cd ../tool
214   # ./dfuse.py ../src/gnuk.hex
215
216 Then, remove the jumper and reset the board.
217
218
219 STBee Mini
220 ----------
221
222 Reset the board with "USER" switch pushed.  Type following to write
223 to flash:
224
225   # cd ../tool
226   # ./dfuse.py ../src/gnuk.hex
227
228 Then, reset the board.
229
230
231 Debug enabled
232 -------------
233
234 If you compiled with --enable-debug option, Gnuk has two interfaces
235 (one is CCID/ICCD device and another is virtual COM port).  Open
236 virtual COM port by:
237
238   $ cu -l /dev/ttyACM0
239
240 and you will see debug output of Gnuk.
241
242
243 Libccid fix needed
244 ------------------
245
246 For libccid (< 1.4.1), we need following change:
247
248 --- /etc/libccid_Info.plist.dpkg-dist   2009-07-29 06:50:20.000000000 +0900
249 +++ /etc/libccid_Info.plist     2010-09-05 09:09:49.000000000 +0900
250 @@ -104,6 +104,7 @@
251  
252         <key>ifdVendorID</key>
253         <array>
254 +               <string>0x234B</string>
255                 <string>0x08E6</string>
256                 <string>0x08E6</string>
257                 <string>0x08E6</string>
258 @@ -237,6 +238,7 @@
259  
260         <key>ifdProductID</key>
261         <array>
262 +               <string>0x0000</string>
263                 <string>0x2202</string>
264                 <string>0x3437</string>
265                 <string>0x3438</string>
266 @@ -370,6 +372,7 @@
267  
268         <key>ifdFriendlyName</key>
269         <array>
270 +               <string>FSIJ USB Token</string>
271                 <string>Gemplus Gem e-Seal Pro</string>
272                 <string>Gemplus GemPC Twin</string>
273                 <string>Gemplus GemPC Key</string>
274 ------------------
275
276 This entry has been added into libccid 1.4.1 already ([r5425]).
277
278
279 Testing Gnuk
280 ------------
281
282 Try following to see Gnuk runs:
283
284   $ gpg --card-status
285
286
287 For more, see doc/DEMO.
288
289
290
291 How to debug
292 ============
293
294 We can use GDB.
295
296   $ arm-none-eabi-gdb gnuk.elf
297
298
299 Inside GDB, we can connect OpenOCD by:
300
301   (gdb) target remote localhost:3333
302
303
304 You can see the output of PCSCD:
305
306   # /etc/init.d/pcscd stop
307   # LIBCCID_ifdLogLevel=7 /usr/sbin/pcscd --debug --foreground
308
309
310 You can observe the traffic of USB using "usbmon".  See the file:
311 linux/Documentation/usb/usbmon.txt
312
313
314 Read-only Git Repository
315 ========================
316
317 You can get it by:
318
319   $ git clone http://www.gniibe.org/git/gnuk.git/
320
321
322 Information on the Web
323 ======================
324
325 Please see: http://www.fsij.org/gnuk/
326
327
328 Your Contributions
329 ==================
330
331 FSIJ welcomes your contributions.  Please assign your copyright
332 to FSIJ (if possible).
333
334
335 Foot note
336 ==========
337 * NUK(R) is a registered trademark owend by MAPA GmbH, Germany.
338 --