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