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