fixes and enhancements
[gnuk/gnuk.git] / README
1 Gnuk - software for GPG USB Token
2
3                                                             Version 0.2
4                                                              2010-09-10
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 Please look at the graphics of "gnuk.svg" for the software name.
16
17 I wish that Gnuk will be a developer's soother who uses GnuPG.  I have
18 been nervous of storing secret key(s) on usual secondary storage.
19 While I want to work at different places, but it is not the choice for
20 me to bring a card reader all the time.  With Gnuk, this issue will be
21 solved by a USB token which is small enough.
22
23
24 Release notes
25 =============
26
27 This is second release of Gnuk.  While it works somehow, it is still
28 experimental.
29
30 Tested features are:
31
32         * Personalization of the card
33
34           * Changing Login name, URL, Name, Sex, Language, etc.
35
36         * Password handling (PW1, RC, PW3)
37
38         * Key import for both of key for digital signing and key for
39           decryption.
40
41         * PSO: Digital Signature
42
43         * PSO: Decipher
44
45 It is known not-working well:
46
47         * Key import multiple times
48
49         * Changing value of password status bytes (0x00C4).
50
51
52 Targets
53 =======
54
55 We use Olimex STM32-H103 board.
56
57 I think that it could run on Olimex STM32-P103, STBee, or STBee mini
58 too.  Besides, we are porting it to STM32 Primer 2.
59
60
61 Souce code
62 ==========
63
64 Gnuk source code is under src/ directory.
65
66
67 License
68 =======
69
70 It is distributed under GNU General Public Licence version 3 or later
71 (GPLv3+).
72
73
74 External source code
75 ====================
76
77 Gnuk is distributed with external source code.
78
79 * ChibiOS_2.0.2/  -- ChibiOS/RT 2.0.2
80
81   Taken from http://chibios.sourceforge.net/
82   Note that CRLF is converted to LF in this repository.
83   We use ChibiOS/RT as the kernel for Gnuk.
84
85 * polarssl-0.14.0/  -- PolarSSL 0.14.0
86
87   Taken from http://polarssl.org/
88   We use PolarSSL for RSA computation.
89
90 * STM32_USB-FS-Device_Driver/ -- a part of USB-FS-Device_Lib
91 * Virtual_COM_Port/ -- a part of USB-FS-Device_Lib
92
93   STM32F10x USB Full Speed Device Library (USB-FS-Device_Lib)
94   is a STM32F10x library for USB functionality.
95
96   I took Libraries/STM32_USB-FS-Device_Driver and 
97   Project/Virtual_COM_Port in STM32_USB-FS-Device_Lib distribution.
98   See http://www.st.com for detail.
99
100
101 Host Requirements
102 =================
103
104 For GNU/Linux, libccid version >= 1.3.11 is required.
105 libccid version == 1.3.9 is known not working well by the issue [r4235].
106
107
108 How to compile
109 ==============
110
111 You need GNU toolchain and newlib for 'arm-none-eabi' target.
112
113 See http://github.com/esden/summon-arm-toolchain/ for preparation of
114 GNU Toolchain for 'arm-none-eabi' target.
115
116   $ cd gnuk-VERSION/src
117
118 Edit the Makefile.  Comment out the line:
119 ----------------
120 ENABLE_DEBUG=1
121 ----------------
122
123 if you don't want to debug Gnuk.
124
125 Type:
126
127   $ make
128
129 In the make process, it takes time for the command of
130
131    dd if=/dev/random bs=1 of=random_bits count=1024
132
133 Don't just wait, but do some other work on your PC.
134 /dev/random needs entropy to finish.
135
136 Then, we will have "gnuk.elf".
137
138
139 How to run
140 ==========
141
142 If you are using Olimex JTAG-Tiny, type following to invoke OpenOCD:
143
144   $ openocd -f interface/olimex-jtag-tiny.cfg -f board/olimex_stm32_h103.cfg
145
146 Then, with another terminal, type following to write "gnuk.elf" to Flash ROM:
147
148   $ telnet localhost 4444
149   > reset halt
150   > flash write_image erase gnuk.elf
151   > reset
152   > exit
153   $ 
154
155 If you compiled with ENABLE_DEBUG=1, Gnuk has two interfaces
156 (one is CCID/ICCD device and another is virtual COM port).  Open
157 virtual COM port by:
158
159   $ cu -l /dev/ttyACM0
160
161 and you will see debug output of Gnuk.
162
163 For libccid, we need following change:
164
165 --- /etc/libccid_Info.plist.dpkg-dist   2009-07-29 06:50:20.000000000 +0900
166 +++ /etc/libccid_Info.plist     2010-09-05 09:09:49.000000000 +0900
167 @@ -104,6 +104,7 @@
168  
169         <key>ifdVendorID</key>
170         <array>
171 +               <string>0x234B</string>
172                 <string>0x08E6</string>
173                 <string>0x08E6</string>
174                 <string>0x08E6</string>
175 @@ -237,6 +238,7 @@
176  
177         <key>ifdProductID</key>
178         <array>
179 +               <string>0x0000</string>
180                 <string>0x2202</string>
181                 <string>0x3437</string>
182                 <string>0x3438</string>
183 @@ -370,6 +372,7 @@
184  
185         <key>ifdFriendlyName</key>
186         <array>
187 +               <string>FSIJ USB Token</string>
188                 <string>Gemplus Gem e-Seal Pro</string>
189                 <string>Gemplus GemPC Twin</string>
190                 <string>Gemplus GemPC Key</string>
191 ------------------
192
193 Then, try following to see Gnuk runs:
194
195   $ gpg --card-status
196
197
198 For more, see doc/DEMO.
199
200
201
202 How to debug
203 ============
204
205 We can use GDB.
206
207   $ arm-none-eabi-gdb gnuk.elf
208
209
210 Inside GDB, we can connect OpenOCD by:
211
212   (gdb) target remote localhost:3333
213
214
215 You can see output of PCSCD:
216
217   # /etc/init.d/pcscd stop
218   # LIBCCID_ifdLogLevel=7 /usr/sbin/pcscd --debug --foreground
219
220
221 You can observe the traffic of USB using "usbmon".  See the file:
222 linux/Documentation/usb/usbmon.txt
223
224
225
226 Development history
227 ===================
228
229 Initially, the development was started with a copy of the files in
230 ChibiOS_2.0.2/demos/ARMCM3-STM32F103-GCC/*, Makefile, linker script,
231 and header files (chconf.h, halconf.h, and mcuconf.h).
232
233 Since this is the initial release, some garbages may still remain.
234 --