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