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