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