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