buf fix of password change
[gnuk/gnuk.git] / README
1 Gnuk - software for GPG USB Token
2
3                                                            Version 0.11
4                                                              2011-04-15
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(R), always, everywhere.  I will be with a
23 USB Token by "Gnuk" everywhere.
24
25
26 FAQ
27 ===
28
29 Q1: What's kind of key algorithm is supported?
30 A1: Gnuk only supports 2048-bit RSA.
31
32 Q2: How long does it take for digital signing?
33 A2: It takes two seconds or so. 
34
35 Q3: What's your recommendation for target board?
36 A3: Orthodox choice is Olimex STM32-H103.
37     If you have skill of electronics and like DIY, STM32 part of STM8S
38     Discovery Kit might be the best choice.
39
40 Q4: What's version of GnuPG are you using?
41 A4: In Debian GNU/Linux system, I use GnuPG 2.0.14-2 (in sid).
42
43 Q5: What's version of pcscd and libccid are you using?
44 A5: In Debian GNU/Linux system, I use pcscd 1.5.5-4 and libccid 1.3.11-2,
45     which is in squeeze.  Note that you need to edit /etc/libccid_Info.plist
46     when using libccid (< 1.4.1).
47
48 Q6: What kinds of hardware is required for development?
49 A6: You need a target board plus JTAG debugger.  If you just want to
50     test Gnuk for target boards with DfuSe, JTAG debugger is not
51     the requirement.  Note that for real use, you need JTAG debugger
52     to enable flash ROM protection.
53
54
55 Release notes
56 =============
57
58 This is twelfth release of Gnuk.  While it works well for specific
59 usages and it is considered stable, it is still somewhat experimental.
60 Note that you need to write random bits after installation of gnuk
61 executable to the chip.  This procedure is required to share a single
62 executable among multiple devices.
63
64 Tested features are:
65
66         * Personalization of the card
67
68           * Changing Login name, URL, Name, Sex, Language, etc.
69
70         * Password handling (PW1, RC, PW3)
71
72         * Key import for three types:
73
74           * key for digital signing
75
76           * key for decryption
77
78           * key for authentication
79
80         * PSO: Digital Signature
81
82         * PSO: Decipher
83
84         * INTERNAL AUTHENTICATE
85
86         * Changing value of password status bytes (0x00C4)
87
88         * Verify with pin pad
89
90         * Modify with pin pad
91
92 It is known not-working well:
93
94         * For some version of kernel and libccid, --enable-debug can't
95           work well.  Please disable DEBUG option if it doesn't work well.
96
97         * Card holder certificate
98           It is implemented in Gnuk side.  But its size matters (>
99           1KB).  GnuPG cannot handle a data object of large size with
100           PC/SC backend.  Specifically, handle_transmit function in
101           pcsc-wrapper.c uses the buffer of size 1024-byte.
102
103 Not supported feature(s):
104
105         * Overriding key import.  You need to remove all keys first.
106
107         * Key generation
108
109
110 Targets
111 =======
112
113 We use Olimex STM32-H103 board.  We also use STM32 part of STM8S
114 Discovery Kit.
115
116 With DfuSe support, CQ STARM, STBee, and STBee Mini are also our
117 targets.  But those targets with DfuSe are basically not for normal
118 use but for experiments, because it would be impossible for DfuSe to
119 disable read from flash.  For real use, please consider killing DfuSe
120 and enable read protection using JTAG debugger.
121
122 I think that it could run on Olimex STM32-P103, or other boards with
123 STM32F103.  Besides, we are porting it to STM32 Primer 2.
124
125 For PIN-pad support, I connect a consumer IR receive module to STBee
126 Mini and STM8S Discovery Kit, and use controller for TV.  PIN
127 verification is supported by this configuration.  Yes, it is not
128 secure at all, since it is very easy to monitor IR output of the
129 controllers.  It is just an experiment.  Note that hardware needed for
130 this experiment is only a consumer IR receive module which is as cheap
131 as 50 JPY.
132
133 Another PIN-pad support is connecting rotary encoder, push switch and
134 7-segment LED display.  Both of PIN verification and PIN modification
135 are supported for this circuit extension.
136
137
138 Souce code
139 ==========
140
141 Gnuk source code is under src/ directory.
142
143
144 License
145 =======
146
147 It is distributed under GNU General Public Licence version 3 or later
148 (GPLv3+).  Please see src/COPYING.
149
150 Please note that it is distributed with external source code too.
151 Please read relevant licenses for external source code, too.
152
153 The author(s) of Gnuk expect users of Gnuk will be able to access the
154 source code of Gnuk, so that users can study the code and can modify
155 if needed.  This doesn't mean person who has a USB Token by Gnuk
156 should be able to acess everything on the Token, regardless of its
157 protections.  Private keys, random bytes, and other information should
158 be protected properly.
159
160
161 External source code
162 ====================
163
164 Gnuk is distributed with external source code.
165
166 * ChibiOS_2.0.8/  -- ChibiOS/RT 2.0.8
167
168   Taken from http://chibios.sourceforge.net/
169   Note that CRLF is converted to LF in this repository.
170   We use ChibiOS/RT as the kernel for Gnuk.
171
172 * polarssl-0.14.0/  -- PolarSSL 0.14.0
173
174   Taken from http://polarssl.org/
175   We use PolarSSL for RSA computation, AES encryption/decryption
176   and SHA-1 computation.
177
178 * STM32_USB-FS-Device_Driver/ -- a part of USB-FS-Device_Lib
179 * Virtual_COM_Port/ -- a part of USB-FS-Device_Lib
180
181   STM32F10x USB Full Speed Device Library (USB-FS-Device_Lib)
182   is a STM32F10x library for USB functionality.
183
184   I took Libraries/STM32_USB-FS-Device_Driver and 
185   Project/Virtual_COM_Port in STM32_USB-FS-Device_Lib distribution.
186   See http://www.st.com/ for detail.
187
188
189 Host Requirements
190 =================
191
192 For GNU/Linux, libccid version >= 1.3.11 is required.
193 libccid version == 1.3.9 is known not working well by the issue [r4235].
194
195 I think that it should not be requirment but the kernel version of my use is:
196 Linux version 2.6.32-5-686 (Debian 2.6.32-18) (ben@decadent.org.uk) (gcc version 4.3.5 (Debian 4.3.5-2) ) #1 SMP Sat Jul 24 02:27:10 UTC 2010
197
198 Linux 2.6.30 is known *NOT* working well with DEBUG option.
199 Linux 2.6.24 is known working well with DEBUG option.
200
201
202 How to compile
203 ==============
204
205 You need GNU toolchain and newlib for 'arm-none-eabi' target.
206
207 See http://github.com/esden/summon-arm-toolchain/ for preparation of
208 GNU Toolchain for 'arm-none-eabi' target.
209
210 Change directory to `src':
211
212   $ cd gnuk-VERSION/src
213
214 Then, run `configure':
215
216   $ ./configure
217
218 Type:
219
220   $ make
221
222 Then, we will have "gnuk.elf".
223
224
225 How to install
226 ==============
227
228 Olimex STM32-H103 board
229 -----------------------
230
231 If you are using Olimex JTAG-Tiny, type following to invoke OpenOCD:
232
233   $ openocd -f interface/olimex-jtag-tiny.cfg -f board/olimex_stm32_h103.cfg
234
235 Then, with another terminal, type following to write "gnuk.elf" to Flash ROM:
236
237   $ telnet localhost 4444
238   > reset halt
239   > flash write_image erase gnuk.elf
240   > reset
241   > exit
242   $ 
243
244
245 STM8S Discovery Kit
246 -------------------
247
248 If you are using FTDI-2232D module and the connection is standard, type:
249
250   $ openocd -f interface/openocd-usb.cfg -f target/stm32.cfg
251
252 Initially, the flash ROM of the chip is protected.  you need to do:
253
254   $ telnet localhost 4444
255   > reset halt
256   > stm32x unlock 0
257   > reset
258   > shutdown
259   $ 
260
261 and re-connect the board.  Note that power-off / power-on sequence is
262 required to reset flash ROM.
263
264 Then, invoke OpenOCD again and telnet to connect OpenCD and write
265 image as above example of Olimex STM32-H103.
266
267
268 CQ STARM
269 --------
270
271 Put jumper for J6 to enable DfuSe.  Connecting the board, and type:
272
273   # cd ../tool
274   # ./dfuse.py ../src/gnuk.hex
275
276 Then, remove the jumper and reset the board.
277
278
279 STBee and STBee Mini
280 --------------------
281
282 Reset the board with "USER" switch pushed.  Type following to write
283 to flash:
284
285   # cd ../tool
286   # ./dfuse.py ../src/gnuk.hex
287
288 Then, reset the board.
289
290
291 How to protect flash ROM
292 ========================
293
294 Invoke your OpenOCD and type:
295
296   $ telnet localhost 4444
297   > reset halt
298   > stm32x lock 0
299   > reset
300   > shutdown
301
302 After power-off / power-on sequence, the contents of flash ROM cannot
303 be accessible from JTAG debugger.
304
305 Note that it would be still possible for some implementation of DfuSe
306 to access the contents.  If you want to protect, killing DfuSe and
307 accessing by JTAG debugger is recommended.
308
309
310 How to configure
311 ================
312
313 You need python and pyscard (python-pyscard package in Debian) or
314 PyUSB (python-usb package in Debian).
315
316 (1) In the 'src' directory, type
317
318   $ make random_bits
319
320 In this process, it takes time for the command of
321
322    dd if=/dev/random bs=1 of=random_bits count=1024
323
324 Don't just wait, but do some other works on your PC.
325 /dev/random needs entropy to finish.
326
327
328 (2) [pyscard] Stop scdaemon
329     [PyUSB] Stop the pcsc daemon.
330
331 If scdaemon is running, please kill it, or you will get "Smartcard
332 Exception" by "Sharing violation".
333
334   $ killall -9 scdaemon
335
336 In case of PyUSB tool, you need to stop pcscd.
337
338   # /etc/init.d/pcscd stop
339
340
341 (3) Write the random bits to the device
342
343 Connect your board to USB port of your PC.  And invoke gnuk_put_binary.py:
344
345   $ ../tool/gnuk_put_binary.py -r random_bits
346   random_bits: 1024
347   Updating random bits
348   ...
349
350
351 (4) [Optional] Write fixed serial number
352
353 If you use fixed serial number in the file 'GNUK_SERIAL_NUMBER', you can do:
354
355   $ EMAIL=<YOUR-EMAIL-ADDRESS> ../tool/gnuk_put_binary.py -s ../GNUK_SERIAL_NUMBER
356   Writing serial number
357   ...
358
359 (5) [Optional] Write card holder certificate
360
361 If you have card holder certificate binary file, you can do:
362
363   $ ../tool/gnuk_put_binary.py ../../<YOUR-CERTIFICATE>.bin 
364   ../../<YOUR-CERTIFICATE>.bin: <LENGTH-OF-YOUR-CERTIFICATE>
365   Updating card holder certificate
366   ...
367
368
369 How to run
370 ==========
371
372 Debug enabled
373 -------------
374
375 If you compiled with --enable-debug option, Gnuk has two interfaces
376 (one is CCID/ICCD device and another is virtual COM port).  Open
377 virtual COM port by:
378
379   $ cu -l /dev/ttyACM0
380
381 and you will see debug output of Gnuk.
382
383
384 Libccid fix needed
385 ------------------
386
387 For libccid (< 1.4.1), we need following change:
388
389 --- /etc/libccid_Info.plist.dpkg-dist   2009-07-29 06:50:20.000000000 +0900
390 +++ /etc/libccid_Info.plist     2010-09-05 09:09:49.000000000 +0900
391 @@ -104,6 +104,7 @@
392  
393         <key>ifdVendorID</key>
394         <array>
395 +               <string>0x234B</string>
396                 <string>0x08E6</string>
397                 <string>0x08E6</string>
398                 <string>0x08E6</string>
399 @@ -237,6 +238,7 @@
400  
401         <key>ifdProductID</key>
402         <array>
403 +               <string>0x0000</string>
404                 <string>0x2202</string>
405                 <string>0x3437</string>
406                 <string>0x3438</string>
407 @@ -370,6 +372,7 @@
408  
409         <key>ifdFriendlyName</key>
410         <array>
411 +               <string>FSIJ USB Token</string>
412                 <string>Gemplus Gem e-Seal Pro</string>
413                 <string>Gemplus GemPC Twin</string>
414                 <string>Gemplus GemPC Key</string>
415 ------------------
416
417 This entry has been added into libccid 1.4.1 already ([r5425]).
418
419
420 Testing Gnuk
421 ------------
422
423 Try following to see Gnuk runs:
424
425   $ gpg --card-status
426
427
428 For more, see doc/DEMO.
429
430
431
432 How to debug
433 ============
434
435 We can use GDB.
436
437   $ arm-none-eabi-gdb gnuk.elf
438
439
440 Inside GDB, we can connect OpenOCD by:
441
442   (gdb) target remote localhost:3333
443
444
445 You can see the output of PCSCD:
446
447   # /etc/init.d/pcscd stop
448   # LIBCCID_ifdLogLevel=7 /usr/sbin/pcscd --debug --foreground
449
450
451 You can observe the traffic of USB using "usbmon".  See the file:
452 linux/Documentation/usb/usbmon.txt
453
454
455 Read-only Git Repository
456 ========================
457
458 You can browse at http://www.gniibe.org/gitweb/gnuk.git/
459
460 You can get it by:
461
462   $ git clone git://www.gniibe.org/gnuk.git/
463
464 or
465
466   $ git clone http://www.gniibe.org/git/gnuk.git/
467
468
469
470 Information on the Web
471 ======================
472
473 Please see: http://www.fsij.org/gnuk/
474
475
476 Your Contributions
477 ==================
478
479 FSIJ welcomes your contributions.  Please assign your copyright
480 to FSIJ (if possible).
481
482
483 Foot note
484 ==========
485 * NUK(R) is a registered trademark owend by MAPA GmbH, Germany.
486 --