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