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