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