Release 0.1.
[gnuk/gnuk.git] / README
1 Gnuk - software for GPG USB Token
2
3                                                             Version 0.1
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 runs on Olimex STM32-P103, STBee, or STBee mini too.
58 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 a part of
97   Project/ in STM32_USB-FS-Device_Lib distribution.
98   See http://www.st.com for detail.
99
100
101 How to compile
102 ==============
103
104 You need GNU toolchain and newlib for 'arm-none-eabi' target.
105
106 See http://github.com/esden/summon-arm-toolchain/ for preparation of
107 GNU Toolchain for 'arm-none-eabi' target.
108
109   $ cd gnuk-VERSION/src
110
111 Edit the Makefile.  Comment out the line:
112 ----------------
113 ENABLE_DEBUG=1
114 ----------------
115
116 if you don't want to debug Gnuk.
117
118 Type:
119
120   $ make
121
122 In the make process, it takes time for the command of
123
124    dd if=/dev/random bs=1 of=random_bits count=1024
125
126 Don't just wait, but do some other work on your PC.
127 /dev/random needs entropy to finish.
128
129 Then, we will have "gnuk.elf".
130
131
132 How to run
133 ==========
134
135 If you are using Olimex JTAG-Tiny, type following to invoke OpenOCD:
136
137   $ openocd -f interface/olimex-jtag-tiny.cfg -f board/olimex_stm32_h103.cfg
138
139 Then, with another terminal, type following to write "gnuk.elf" to Flash ROM:
140
141   $ telnet localhost 4444
142   > reset halt
143   > flash write_image erase gnuk.elf
144   > reset
145   > exit
146   $ 
147
148 If you compiled with ENABLE_DEBUG=1, Gnuk has two interfaces
149 (one is CCID/ICCD device and another is virtual COM port).  Open
150 virtual COM port by:
151
152   $ cu -l /dev/ttyACM0
153
154 and you will see debug output of Gnuk.
155
156 For libccid, we need following change:
157
158 --- /etc/libccid_Info.plist.dpkg-dist   2009-07-29 06:50:20.000000000 +0900
159 +++ /etc/libccid_Info.plist     2010-09-05 09:09:49.000000000 +0900
160 @@ -104,6 +104,7 @@
161  
162         <key>ifdVendorID</key>
163         <array>
164 +               <string>0x234B</string>
165                 <string>0x08E6</string>
166                 <string>0x08E6</string>
167                 <string>0x08E6</string>
168 @@ -237,6 +238,7 @@
169  
170         <key>ifdProductID</key>
171         <array>
172 +               <string>0x0000</string>
173                 <string>0x2202</string>
174                 <string>0x3437</string>
175                 <string>0x3438</string>
176 @@ -370,6 +372,7 @@
177  
178         <key>ifdFriendlyName</key>
179         <array>
180 +               <string>FSIJ USB Token</string>
181                 <string>Gemplus Gem e-Seal Pro</string>
182                 <string>Gemplus GemPC Twin</string>
183                 <string>Gemplus GemPC Key</string>
184 ------------------
185
186
187 Then, try following to see Gnuk runs:
188
189   $ gpg --card-status
190
191
192 For more, see doc/DEMO.
193
194
195
196 How to debug
197 ============
198
199 We can use GDB.
200
201   $ arm-none-eabi-gdb gnuk.elf
202
203
204 Inside GDB, we can connect OpenOCD by:
205
206   (gdb) target remote localhost:3333
207
208
209 You can see output of PCSCD:
210
211   # /etc/init.d/pcscd stop
212   # LIBCCID_ifdLogLevel=7 /usr/sbin/pcscd --debug --foreground
213
214
215 You can observe the traffic of USB using "usbmon".  See the file:
216 linux/Documentation/usb/usbmon.txt
217
218
219
220 Development history
221 ===================
222
223 Initially, the development was started with a copy of the files in
224 ChibiOS_2.0.2/demos/ARMCM3-STM32F103-GCC/*, Makefile, linker script,
225 and header files (chconf.h, halconf.h, and mcuconf.h).
226
227 Since this is the initial release, some garbages may still remain.
228 --