2010-09-09 08:50:34 +00:00
|
|
|
Gnuk - software for GPG USB Token
|
2010-08-30 11:02:22 +00:00
|
|
|
|
2011-02-10 04:57:23 +00:00
|
|
|
Version 0.10
|
|
|
|
2011-02-10
|
2010-09-05 16:55:29 +00:00
|
|
|
Niibe Yutaka
|
|
|
|
Free Software Initiative of Japan
|
2010-08-30 11:02:22 +00:00
|
|
|
|
2010-09-09 08:50:34 +00:00
|
|
|
What's Gnuk?
|
|
|
|
============
|
2010-08-30 11:02:22 +00:00
|
|
|
|
2010-11-02 03:37:13 +00:00
|
|
|
Gnuk is software implementation of a USB token for GNU Privacy Guard.
|
2010-09-05 09:10:54 +00:00
|
|
|
Gnuk supports OpenPGP card protocol version 2, and it runs on STM32
|
|
|
|
processor.
|
2010-08-30 11:02:22 +00:00
|
|
|
|
2010-09-09 08:50:34 +00:00
|
|
|
I wish that Gnuk will be a developer's soother who uses GnuPG. I have
|
|
|
|
been nervous of storing secret key(s) on usual secondary storage.
|
|
|
|
While I want to work at different places, but it is not the choice for
|
|
|
|
me to bring a card reader all the time. With Gnuk, this issue will be
|
|
|
|
solved by a USB token which is small enough.
|
|
|
|
|
2010-09-10 07:41:00 +00:00
|
|
|
Please look at the graphics of "gnuk.svg" for the software name. My
|
2010-09-13 02:47:21 +00:00
|
|
|
son used to be with his NUK(R), always, everywhere. I will be with a
|
|
|
|
USB Token by Gnuk everywhere.
|
2010-09-10 01:52:07 +00:00
|
|
|
|
2010-08-30 11:02:22 +00:00
|
|
|
|
|
|
|
Release notes
|
|
|
|
=============
|
|
|
|
|
2011-02-10 04:57:23 +00:00
|
|
|
This is eleventh release of Gnuk. While it works well for specific
|
|
|
|
usages, it is still experimental. Note that you need to write random
|
|
|
|
bits after installation of gnuk executable to the chip from this
|
|
|
|
release. This procedure is required to share a single executable
|
|
|
|
among multiple devices.
|
2010-09-05 09:10:54 +00:00
|
|
|
|
2010-09-05 17:30:38 +00:00
|
|
|
Tested features are:
|
2010-09-05 09:10:54 +00:00
|
|
|
|
|
|
|
* Personalization of the card
|
|
|
|
|
|
|
|
* Changing Login name, URL, Name, Sex, Language, etc.
|
|
|
|
|
|
|
|
* Password handling (PW1, RC, PW3)
|
|
|
|
|
2010-11-05 09:25:47 +00:00
|
|
|
* Key import for three types:
|
|
|
|
|
|
|
|
* key for digital signing
|
|
|
|
|
|
|
|
* key for decryption
|
|
|
|
|
|
|
|
* key for authentication
|
2010-09-05 09:10:54 +00:00
|
|
|
|
|
|
|
* PSO: Digital Signature
|
|
|
|
|
2010-09-09 08:50:34 +00:00
|
|
|
* PSO: Decipher
|
2010-08-30 11:02:22 +00:00
|
|
|
|
2010-10-20 01:20:45 +00:00
|
|
|
* INTERNAL AUTHENTICATE
|
|
|
|
|
2011-01-07 07:18:47 +00:00
|
|
|
* Changing value of password status bytes (0x00C4)
|
|
|
|
|
|
|
|
* Verify with pin pad
|
2010-11-30 01:04:30 +00:00
|
|
|
|
2011-01-19 06:44:37 +00:00
|
|
|
* Modify with pin pad
|
|
|
|
|
2010-09-09 08:50:34 +00:00
|
|
|
It is known not-working well:
|
2010-08-30 11:02:22 +00:00
|
|
|
|
2010-10-14 08:08:09 +00:00
|
|
|
* For some version of kernel and libccid, --enable-debug can't
|
2010-09-13 02:47:21 +00:00
|
|
|
work well. Please disable DEBUG option if it doesn't work well.
|
|
|
|
|
2011-01-28 15:00:47 +00:00
|
|
|
* Card holder certificate
|
|
|
|
It is implemented in Gnuk side. But its size matters (>
|
|
|
|
1KB). GnuPG cannot handle a data object of large size with
|
|
|
|
PC/SC backend. Specifically, handle_transmit function in
|
|
|
|
pcsc-wrapper.c uses the buffer of size 1024-byte.
|
2010-11-04 01:33:20 +00:00
|
|
|
|
2010-12-03 08:35:22 +00:00
|
|
|
Not supported feature(s):
|
|
|
|
|
|
|
|
* Overriding key import. You need to remove all keys first.
|
|
|
|
|
2011-02-10 04:57:23 +00:00
|
|
|
* Key generation
|
2010-09-05 09:10:54 +00:00
|
|
|
|
|
|
|
Targets
|
|
|
|
=======
|
2010-08-30 11:02:22 +00:00
|
|
|
|
2010-11-30 01:04:30 +00:00
|
|
|
We use Olimex STM32-H103 board. We also use STM32 part of STM8S
|
|
|
|
Discovery Kit.
|
|
|
|
|
2011-01-28 15:00:47 +00:00
|
|
|
With DfuSe support, CQ STARM, STBee, and STBee Mini are also our
|
|
|
|
targets. But those targets with DfuSe are basically not for normal
|
|
|
|
use but for experiments, because it would be impossible for DfuSe to
|
|
|
|
disable read from flash. For real use, please consider killing DfuSe
|
|
|
|
and enable read protect using JTAG debugger.
|
2010-08-30 11:02:22 +00:00
|
|
|
|
2011-01-28 15:00:47 +00:00
|
|
|
I think that it could run on Olimex STM32-P103, or other boards with
|
|
|
|
STM32F103. Besides, we are porting it to STM32 Primer 2.
|
2010-08-30 11:02:22 +00:00
|
|
|
|
2011-01-14 06:47:15 +00:00
|
|
|
For PIN-pad support, I connect a consumer IR receive module to STBee
|
2011-01-19 06:44:37 +00:00
|
|
|
Mini and STM8S Discovery Kit, and use controller for TV. PIN
|
|
|
|
verification is supported by this configuration. Yes, it is not
|
|
|
|
secure at all, since it is very easy to monitor IR output of the
|
2011-01-28 15:00:47 +00:00
|
|
|
controllers. It is just an experiment. Note that hardware needed for
|
|
|
|
this experiment is only a consumer IR receive module which is as cheap
|
|
|
|
as 50 JPY.
|
2011-01-14 06:47:15 +00:00
|
|
|
|
2011-01-28 15:00:47 +00:00
|
|
|
Another PIN-pad support is connecting rotary encoder, push switch and
|
2011-01-19 06:44:37 +00:00
|
|
|
7-segment LED display. Both of PIN verification and PIN modification
|
|
|
|
are supported for this circuit extension.
|
|
|
|
|
2010-08-30 11:02:22 +00:00
|
|
|
|
2010-08-10 03:11:02 +00:00
|
|
|
Souce code
|
|
|
|
==========
|
|
|
|
|
2010-08-30 11:02:22 +00:00
|
|
|
Gnuk source code is under src/ directory.
|
|
|
|
|
|
|
|
|
|
|
|
License
|
|
|
|
=======
|
|
|
|
|
|
|
|
It is distributed under GNU General Public Licence version 3 or later
|
2010-09-13 02:47:21 +00:00
|
|
|
(GPLv3+). Please see src/COPYING.
|
|
|
|
|
|
|
|
Please note that it is distributed with external source code too.
|
|
|
|
Please read relevant licenses for external source code, too.
|
|
|
|
|
|
|
|
The author(s) of Gnuk expect users of Gnuk will be able to access the
|
2011-01-28 15:00:47 +00:00
|
|
|
source code of Gnuk, so that users can study the code and can modify
|
|
|
|
if needed. This doesn't mean person who has a USB Token by Gnuk
|
|
|
|
should be able to acess everything on the Token, regardless of its
|
|
|
|
protections. Private keys, random bytes, and other information should
|
|
|
|
be protected properly.
|
2010-08-30 11:02:22 +00:00
|
|
|
|
2010-08-10 03:11:02 +00:00
|
|
|
|
2010-08-30 11:02:22 +00:00
|
|
|
External source code
|
|
|
|
====================
|
2010-08-10 03:11:02 +00:00
|
|
|
|
2010-08-30 11:02:22 +00:00
|
|
|
Gnuk is distributed with external source code.
|
|
|
|
|
2010-11-30 04:54:43 +00:00
|
|
|
* ChibiOS_2.0.8/ -- ChibiOS/RT 2.0.8
|
2010-09-05 09:10:54 +00:00
|
|
|
|
|
|
|
Taken from http://chibios.sourceforge.net/
|
|
|
|
Note that CRLF is converted to LF in this repository.
|
|
|
|
We use ChibiOS/RT as the kernel for Gnuk.
|
2010-08-10 03:11:02 +00:00
|
|
|
|
2010-08-30 11:02:22 +00:00
|
|
|
* polarssl-0.14.0/ -- PolarSSL 0.14.0
|
|
|
|
|
2010-09-05 09:10:54 +00:00
|
|
|
Taken from http://polarssl.org/
|
2010-09-13 02:47:21 +00:00
|
|
|
We use PolarSSL for RSA computation, AES encryption/decryption
|
|
|
|
and SHA-1 computation.
|
2010-08-30 11:02:22 +00:00
|
|
|
|
|
|
|
* STM32_USB-FS-Device_Driver/ -- a part of USB-FS-Device_Lib
|
|
|
|
* Virtual_COM_Port/ -- a part of USB-FS-Device_Lib
|
|
|
|
|
2010-09-05 09:10:54 +00:00
|
|
|
STM32F10x USB Full Speed Device Library (USB-FS-Device_Lib)
|
|
|
|
is a STM32F10x library for USB functionality.
|
2010-08-10 03:11:02 +00:00
|
|
|
|
2010-09-09 16:25:44 +00:00
|
|
|
I took Libraries/STM32_USB-FS-Device_Driver and
|
|
|
|
Project/Virtual_COM_Port in STM32_USB-FS-Device_Lib distribution.
|
2011-01-28 15:00:47 +00:00
|
|
|
See http://www.st.com/ for detail.
|
2010-08-18 05:21:58 +00:00
|
|
|
|
|
|
|
|
2010-09-09 16:25:44 +00:00
|
|
|
Host Requirements
|
|
|
|
=================
|
|
|
|
|
|
|
|
For GNU/Linux, libccid version >= 1.3.11 is required.
|
|
|
|
libccid version == 1.3.9 is known not working well by the issue [r4235].
|
|
|
|
|
2010-09-13 02:47:21 +00:00
|
|
|
I think that it should not be requirment but the kernel version of my use is:
|
|
|
|
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
|
|
|
|
|
|
|
|
Linux 2.6.30 is known *NOT* working well with DEBUG option.
|
|
|
|
Linux 2.6.24 is known working well with DEBUG option.
|
|
|
|
|
2010-09-09 16:25:44 +00:00
|
|
|
|
2010-08-30 11:02:22 +00:00
|
|
|
How to compile
|
|
|
|
==============
|
|
|
|
|
2010-09-05 09:10:54 +00:00
|
|
|
You need GNU toolchain and newlib for 'arm-none-eabi' target.
|
2010-08-30 11:02:22 +00:00
|
|
|
|
|
|
|
See http://github.com/esden/summon-arm-toolchain/ for preparation of
|
|
|
|
GNU Toolchain for 'arm-none-eabi' target.
|
|
|
|
|
2010-10-14 08:08:09 +00:00
|
|
|
Change directory to `src':
|
|
|
|
|
2010-08-30 11:02:22 +00:00
|
|
|
$ cd gnuk-VERSION/src
|
2010-09-05 09:10:54 +00:00
|
|
|
|
2010-10-14 08:08:09 +00:00
|
|
|
Then, run `configure':
|
2010-09-05 09:10:54 +00:00
|
|
|
|
2010-10-14 08:08:09 +00:00
|
|
|
$ ./configure
|
2010-09-05 09:10:54 +00:00
|
|
|
|
|
|
|
Type:
|
|
|
|
|
2010-08-30 11:02:22 +00:00
|
|
|
$ make
|
|
|
|
|
|
|
|
Then, we will have "gnuk.elf".
|
|
|
|
|
|
|
|
|
2011-02-10 04:57:23 +00:00
|
|
|
How to install
|
|
|
|
==============
|
2010-08-30 11:02:22 +00:00
|
|
|
|
2010-11-02 03:37:13 +00:00
|
|
|
Olimex STM32-H103 board
|
|
|
|
-----------------------
|
|
|
|
|
2010-08-30 11:02:22 +00:00
|
|
|
If you are using Olimex JTAG-Tiny, type following to invoke OpenOCD:
|
|
|
|
|
|
|
|
$ openocd -f interface/olimex-jtag-tiny.cfg -f board/olimex_stm32_h103.cfg
|
|
|
|
|
|
|
|
Then, with another terminal, type following to write "gnuk.elf" to Flash ROM:
|
|
|
|
|
|
|
|
$ telnet localhost 4444
|
|
|
|
> reset halt
|
|
|
|
> flash write_image erase gnuk.elf
|
|
|
|
> reset
|
|
|
|
> exit
|
|
|
|
$
|
|
|
|
|
2010-11-02 03:37:13 +00:00
|
|
|
|
2011-01-28 15:00:47 +00:00
|
|
|
STM8S Discovery Kit
|
|
|
|
-------------------
|
|
|
|
|
|
|
|
If you are using FTDI-2232D module and the connection is standard, type:
|
|
|
|
|
|
|
|
$ openocd -f interface/openocd-usb.cfg -f target/stm32.cfg
|
|
|
|
|
2011-02-10 04:57:23 +00:00
|
|
|
Initially, the flash ROM of the chip is protected. you need to do:
|
|
|
|
|
|
|
|
$ telnet localhost 4444
|
|
|
|
> reset halt
|
|
|
|
> stm32x unlock 0
|
|
|
|
> reset
|
|
|
|
> shutdown
|
|
|
|
$
|
|
|
|
|
|
|
|
and re-connect the board. Note that power-off / power-on sequence is
|
|
|
|
required to reset flash ROM.
|
|
|
|
|
|
|
|
Then, invoke OpenOCD again and telnet to connect OpenCD and write
|
|
|
|
image as above example of Olimex STM32-H103.
|
|
|
|
|
2011-01-28 15:00:47 +00:00
|
|
|
|
2010-11-02 03:37:13 +00:00
|
|
|
CQ STARM
|
|
|
|
--------
|
|
|
|
|
|
|
|
Put jumper for J6 to enable DfuSe. Connecting the board, and type:
|
|
|
|
|
|
|
|
# cd ../tool
|
|
|
|
# ./dfuse.py ../src/gnuk.hex
|
|
|
|
|
|
|
|
Then, remove the jumper and reset the board.
|
|
|
|
|
|
|
|
|
2011-01-28 15:00:47 +00:00
|
|
|
STBee and STBee Mini
|
|
|
|
--------------------
|
2010-11-02 03:37:13 +00:00
|
|
|
|
|
|
|
Reset the board with "USER" switch pushed. Type following to write
|
|
|
|
to flash:
|
|
|
|
|
|
|
|
# cd ../tool
|
|
|
|
# ./dfuse.py ../src/gnuk.hex
|
|
|
|
|
|
|
|
Then, reset the board.
|
|
|
|
|
|
|
|
|
2011-02-10 04:57:23 +00:00
|
|
|
How to protect flash ROM
|
|
|
|
========================
|
|
|
|
|
|
|
|
Invoke your OpenOCD and type:
|
|
|
|
|
|
|
|
$ telnet localhost 4444
|
|
|
|
> reset halt
|
|
|
|
> stm32x lock 0
|
|
|
|
> reset
|
|
|
|
> shutdown
|
|
|
|
|
|
|
|
After power-off / power-on sequence, the contents of flash ROM cannot
|
|
|
|
be accessible from JTAG debugger.
|
|
|
|
|
|
|
|
Note that it would be still possible for some implementation of DfuSe
|
|
|
|
to access the contents. If you want to protect, killing DfuSe and
|
|
|
|
accessing by JTAG debugger is recommended.
|
|
|
|
|
|
|
|
|
|
|
|
How to configure
|
|
|
|
================
|
|
|
|
|
|
|
|
You need python and PyUSB (python-usb package in Debian).
|
|
|
|
|
|
|
|
(1) In the 'src' directory, type
|
|
|
|
|
|
|
|
$ make random_bits
|
|
|
|
|
|
|
|
In this process, it takes time for the command of
|
|
|
|
|
|
|
|
dd if=/dev/random bs=1 of=random_bits count=1024
|
|
|
|
|
|
|
|
Don't just wait, but do some other works on your PC.
|
|
|
|
/dev/random needs entropy to finish.
|
|
|
|
|
|
|
|
(2) Stop the pcsc daemon.
|
|
|
|
|
|
|
|
# /etc/init.d/pcscd stop
|
|
|
|
|
|
|
|
(3) Write the random bits to the device
|
|
|
|
|
|
|
|
Connect your board to USB port of your PC. And invoke gnuk_put_binary.py:
|
|
|
|
|
2011-02-24 06:54:40 +00:00
|
|
|
# ../tool/gnuk_put_binary.py -r random_bits
|
|
|
|
random_bits: 1024
|
|
|
|
Updating random bits
|
|
|
|
...
|
2011-02-10 04:57:23 +00:00
|
|
|
|
|
|
|
(4) [Optional] Write fixed serial number
|
|
|
|
|
|
|
|
If you use fixed serial number in the file 'GNUK_SERIAL_NUMBER', you can do:
|
|
|
|
|
|
|
|
# EMAIL=<YOUR-EMAIL-ADDRESS> ../tool/gnuk_put_binary.py -s ../GNUK_SERIAL_NUMBER
|
2011-02-24 06:54:40 +00:00
|
|
|
Writing serial number
|
|
|
|
...
|
2011-02-10 04:57:23 +00:00
|
|
|
|
|
|
|
(5) [Optional] Write card holder certificate
|
|
|
|
|
|
|
|
If you have card holder certificate binary file, you can do:
|
|
|
|
|
|
|
|
# ../tool/gnuk_put_binary.py ../../<YOUR-CERTIFICATE>.bin
|
2011-02-24 06:54:40 +00:00
|
|
|
../../<YOUR-CERTIFICATE>.bin: <LENGTH-OF-YOUR-CERTIFICATE>
|
|
|
|
Updating card holder certificate
|
|
|
|
...
|
2011-02-10 04:57:23 +00:00
|
|
|
|
|
|
|
|
|
|
|
How to run
|
|
|
|
==========
|
|
|
|
|
2010-11-02 03:37:13 +00:00
|
|
|
Debug enabled
|
|
|
|
-------------
|
|
|
|
|
2010-10-14 08:08:09 +00:00
|
|
|
If you compiled with --enable-debug option, Gnuk has two interfaces
|
2010-09-05 09:10:54 +00:00
|
|
|
(one is CCID/ICCD device and another is virtual COM port). Open
|
|
|
|
virtual COM port by:
|
|
|
|
|
|
|
|
$ cu -l /dev/ttyACM0
|
|
|
|
|
|
|
|
and you will see debug output of Gnuk.
|
|
|
|
|
2010-11-02 03:37:13 +00:00
|
|
|
|
|
|
|
Libccid fix needed
|
|
|
|
------------------
|
|
|
|
|
2011-01-07 07:18:47 +00:00
|
|
|
For libccid (< 1.4.1), we need following change:
|
2010-09-05 09:10:54 +00:00
|
|
|
|
|
|
|
--- /etc/libccid_Info.plist.dpkg-dist 2009-07-29 06:50:20.000000000 +0900
|
|
|
|
+++ /etc/libccid_Info.plist 2010-09-05 09:09:49.000000000 +0900
|
|
|
|
@@ -104,6 +104,7 @@
|
|
|
|
|
|
|
|
<key>ifdVendorID</key>
|
|
|
|
<array>
|
|
|
|
+ <string>0x234B</string>
|
|
|
|
<string>0x08E6</string>
|
|
|
|
<string>0x08E6</string>
|
|
|
|
<string>0x08E6</string>
|
|
|
|
@@ -237,6 +238,7 @@
|
|
|
|
|
|
|
|
<key>ifdProductID</key>
|
|
|
|
<array>
|
|
|
|
+ <string>0x0000</string>
|
|
|
|
<string>0x2202</string>
|
|
|
|
<string>0x3437</string>
|
|
|
|
<string>0x3438</string>
|
|
|
|
@@ -370,6 +372,7 @@
|
|
|
|
|
|
|
|
<key>ifdFriendlyName</key>
|
|
|
|
<array>
|
|
|
|
+ <string>FSIJ USB Token</string>
|
|
|
|
<string>Gemplus Gem e-Seal Pro</string>
|
|
|
|
<string>Gemplus GemPC Twin</string>
|
|
|
|
<string>Gemplus GemPC Key</string>
|
|
|
|
------------------
|
|
|
|
|
2011-01-07 07:18:47 +00:00
|
|
|
This entry has been added into libccid 1.4.1 already ([r5425]).
|
|
|
|
|
2010-11-02 03:37:13 +00:00
|
|
|
|
|
|
|
Testing Gnuk
|
|
|
|
------------
|
|
|
|
|
|
|
|
Try following to see Gnuk runs:
|
2010-09-05 09:10:54 +00:00
|
|
|
|
|
|
|
$ gpg --card-status
|
|
|
|
|
|
|
|
|
2010-09-05 17:30:38 +00:00
|
|
|
For more, see doc/DEMO.
|
2010-09-05 09:10:54 +00:00
|
|
|
|
|
|
|
|
2010-08-30 11:02:22 +00:00
|
|
|
|
|
|
|
How to debug
|
|
|
|
============
|
2010-08-18 05:21:58 +00:00
|
|
|
|
2010-08-30 11:02:22 +00:00
|
|
|
We can use GDB.
|
2010-08-18 05:21:58 +00:00
|
|
|
|
2010-08-30 11:02:22 +00:00
|
|
|
$ arm-none-eabi-gdb gnuk.elf
|
2010-08-18 05:21:58 +00:00
|
|
|
|
2010-09-05 09:10:54 +00:00
|
|
|
|
|
|
|
Inside GDB, we can connect OpenOCD by:
|
|
|
|
|
|
|
|
(gdb) target remote localhost:3333
|
|
|
|
|
|
|
|
|
2010-09-10 07:41:00 +00:00
|
|
|
You can see the output of PCSCD:
|
2010-09-09 08:50:34 +00:00
|
|
|
|
|
|
|
# /etc/init.d/pcscd stop
|
|
|
|
# LIBCCID_ifdLogLevel=7 /usr/sbin/pcscd --debug --foreground
|
|
|
|
|
|
|
|
|
|
|
|
You can observe the traffic of USB using "usbmon". See the file:
|
|
|
|
linux/Documentation/usb/usbmon.txt
|
|
|
|
|
|
|
|
|
2010-09-10 07:41:00 +00:00
|
|
|
Read-only Git Repository
|
|
|
|
========================
|
|
|
|
|
|
|
|
You can get it by:
|
|
|
|
|
|
|
|
$ git clone http://www.gniibe.org/git/gnuk.git/
|
|
|
|
|
|
|
|
|
|
|
|
Information on the Web
|
|
|
|
======================
|
|
|
|
|
|
|
|
Please see: http://www.fsij.org/gnuk/
|
|
|
|
|
|
|
|
|
|
|
|
Your Contributions
|
|
|
|
==================
|
|
|
|
|
2010-09-12 07:12:17 +00:00
|
|
|
FSIJ welcomes your contributions. Please assign your copyright
|
2010-09-13 02:47:21 +00:00
|
|
|
to FSIJ (if possible).
|
2010-09-10 07:41:00 +00:00
|
|
|
|
2010-09-05 09:10:54 +00:00
|
|
|
|
2010-09-13 02:47:21 +00:00
|
|
|
Foot note
|
|
|
|
==========
|
|
|
|
* NUK(R) is a registered trademark owend by MAPA GmbH, Germany.
|
2010-08-30 11:02:22 +00:00
|
|
|
--
|