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