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