version 0.3
[gnuk/gnuk.git] / README
1 Gnuk - software for GPG USB Token
2
3                                                             Version 0.3
4                                                              2010-10-23
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 If you are using Olimex JTAG-Tiny, type following to invoke OpenOCD:
168
169   $ openocd -f interface/olimex-jtag-tiny.cfg -f board/olimex_stm32_h103.cfg
170
171 Then, with another terminal, type following to write "gnuk.elf" to Flash ROM:
172
173   $ telnet localhost 4444
174   > reset halt
175   > flash write_image erase gnuk.elf
176   > reset
177   > exit
178   $ 
179
180 If you compiled with --enable-debug option, Gnuk has two interfaces
181 (one is CCID/ICCD device and another is virtual COM port).  Open
182 virtual COM port by:
183
184   $ cu -l /dev/ttyACM0
185
186 and you will see debug output of Gnuk.
187
188 For libccid, we need following change:
189
190 --- /etc/libccid_Info.plist.dpkg-dist   2009-07-29 06:50:20.000000000 +0900
191 +++ /etc/libccid_Info.plist     2010-09-05 09:09:49.000000000 +0900
192 @@ -104,6 +104,7 @@
193  
194         <key>ifdVendorID</key>
195         <array>
196 +               <string>0x234B</string>
197                 <string>0x08E6</string>
198                 <string>0x08E6</string>
199                 <string>0x08E6</string>
200 @@ -237,6 +238,7 @@
201  
202         <key>ifdProductID</key>
203         <array>
204 +               <string>0x0000</string>
205                 <string>0x2202</string>
206                 <string>0x3437</string>
207                 <string>0x3438</string>
208 @@ -370,6 +372,7 @@
209  
210         <key>ifdFriendlyName</key>
211         <array>
212 +               <string>FSIJ USB Token</string>
213                 <string>Gemplus Gem e-Seal Pro</string>
214                 <string>Gemplus GemPC Twin</string>
215                 <string>Gemplus GemPC Key</string>
216 ------------------
217
218 Then, try following to see Gnuk runs:
219
220   $ gpg --card-status
221
222
223 For more, see doc/DEMO.
224
225
226
227 How to debug
228 ============
229
230 We can use GDB.
231
232   $ arm-none-eabi-gdb gnuk.elf
233
234
235 Inside GDB, we can connect OpenOCD by:
236
237   (gdb) target remote localhost:3333
238
239
240 You can see the output of PCSCD:
241
242   # /etc/init.d/pcscd stop
243   # LIBCCID_ifdLogLevel=7 /usr/sbin/pcscd --debug --foreground
244
245
246 You can observe the traffic of USB using "usbmon".  See the file:
247 linux/Documentation/usb/usbmon.txt
248
249
250 Read-only Git Repository
251 ========================
252
253 You can get it by:
254
255   $ git clone http://www.gniibe.org/git/gnuk.git/
256
257
258 Information on the Web
259 ======================
260
261 Please see: http://www.fsij.org/gnuk/
262
263
264 Your Contributions
265 ==================
266
267 FSIJ welcomes your contributions.  Please assign your copyright
268 to FSIJ (if possible).
269
270
271 Foot note
272 ==========
273 * NUK(R) is a registered trademark owend by MAPA GmbH, Germany.
274 --