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