2012-06-19 01:19:26 +00:00
|
|
|
Gnuk - An Implementation of USB Cryptographic Token for GnuPG
|
2010-08-30 11:02:22 +00:00
|
|
|
|
2015-07-21 00:25:06 +00:00
|
|
|
Version 1.1.6
|
|
|
|
2015-07-21
|
2012-05-15 01:16:25 +00:00
|
|
|
Niibe Yutaka
|
2010-09-05 16:55:29 +00:00
|
|
|
Free Software Initiative of Japan
|
2010-08-30 11:02:22 +00:00
|
|
|
|
2013-12-20 05:06:48 +00:00
|
|
|
Warning
|
|
|
|
=======
|
|
|
|
|
2015-07-21 00:25:06 +00:00
|
|
|
This is another experimental release of Gnuk, version 1.1.6, which has
|
2013-12-24 05:25:39 +00:00
|
|
|
incompatible changes to Gnuk 1.0.x. Specifically, it now supports
|
|
|
|
overriding key import, but importing keys (or generating keys) results
|
|
|
|
password reset. Please update your documentation for Gnuk Token, so
|
2014-03-07 06:43:05 +00:00
|
|
|
that the instruction of importing keys won't cause any confusion. It
|
2015-07-21 00:25:06 +00:00
|
|
|
has supports of ECDSA (with NIST P256 and secp256k1), EdDSA, and ECDH
|
|
|
|
(with NIST P256, secp256k1, and Curve25519), but this ECC feature is
|
|
|
|
pretty much experimental, and it requires development version of GnuPG
|
|
|
|
with newest version of libgcrypt (Further, for Curve25519, it requires
|
|
|
|
additional patches by me).
|
|
|
|
|
|
|
|
It also support RSA-4096 experimentally, but users should know that it
|
|
|
|
takes more than 8 second to sign/decrypt.
|
|
|
|
|
|
|
|
You will not able to keep using Curve25519 keys, as the key format is
|
|
|
|
subject to change.
|
2013-12-20 05:06:48 +00:00
|
|
|
|
|
|
|
|
2010-09-09 08:50:34 +00:00
|
|
|
What's Gnuk?
|
|
|
|
============
|
2010-08-30 11:02:22 +00:00
|
|
|
|
2012-06-19 01:19:26 +00:00
|
|
|
Gnuk is an implementation of USB cryptographic token for GNU Privacy
|
2015-06-03 07:34:27 +00:00
|
|
|
Guard. Gnuk supports OpenPGP card protocol version 3, and it runs on
|
2011-12-13 05:25:07 +00:00
|
|
|
STM32F103 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.
|
2012-08-03 02:20:13 +00:00
|
|
|
There is a solution with OpenPGP card, but it is not the choice for
|
|
|
|
me, as card reader is not common device. With Gnuk, this issue will
|
|
|
|
be solved by a USB token.
|
2010-09-09 08:50:34 +00:00
|
|
|
|
2010-09-10 07:41:00 +00:00
|
|
|
Please look at the graphics of "gnuk.svg" for the software name. My
|
2012-06-19 01:19:26 +00:00
|
|
|
son used to be with his NUK(R), always, everywhere. Now, I am with a
|
|
|
|
USB Cryptographic Token by "Gnuk", always, everywhere.
|
2011-05-11 02:50:00 +00:00
|
|
|
|
|
|
|
|
|
|
|
FAQ
|
|
|
|
===
|
|
|
|
|
2011-05-13 02:59:05 +00:00
|
|
|
Q0: How Gnuk USB Token is superior than other solutions (OpenPGP
|
2011-10-07 02:01:21 +00:00
|
|
|
card 2.0, GPF Crypto Stick, etc.) ?
|
2011-05-13 02:59:05 +00:00
|
|
|
http://www.g10code.de/p-card.html
|
|
|
|
http://www.privacyfoundation.de/crypto_stick/
|
2012-07-20 04:04:39 +00:00
|
|
|
A0: Good points of Gnuk are:
|
2011-05-13 02:59:05 +00:00
|
|
|
* If you have skill of electronics and like DIY, you can build
|
|
|
|
Gnuk Token cheaper (see Q8-A8).
|
|
|
|
* You can study Gnuk to modify and to enhance. For example, you
|
|
|
|
can implement your own authentication method with some sensor
|
2012-08-03 02:20:13 +00:00
|
|
|
such as an acceleration sensor.
|
2011-05-13 02:59:05 +00:00
|
|
|
* It is "of Free Software"; Gnuk is distributed under GPLv3+,
|
2012-05-15 01:16:25 +00:00
|
|
|
"by Free Software"; Gnuk development requires only Free Software
|
|
|
|
(GNU Toolchain, Python, etc.),
|
2011-05-13 02:59:05 +00:00
|
|
|
"for Free Software"; Gnuk supports GnuPG.
|
|
|
|
|
2011-06-14 23:52:02 +00:00
|
|
|
Q1: What kind of key algorithm is supported?
|
2014-12-13 12:57:38 +00:00
|
|
|
A1: Gnuk version 1.0 only supports RSA 2048.
|
|
|
|
Development version of Gnuk (1.1.x) supports 256-bit ECDSA and EdDSA,
|
|
|
|
as well as RSA 4096-bit. But it takes long time to sign with RSA 4096.
|
2011-05-11 02:50:00 +00:00
|
|
|
|
|
|
|
Q2: How long does it take for digital signing?
|
2011-06-14 23:52:02 +00:00
|
|
|
A2: It takes a second and a half or so.
|
2011-05-11 02:50:00 +00:00
|
|
|
|
|
|
|
Q3: What's your recommendation for target board?
|
|
|
|
A3: Orthodox choice is Olimex STM32-H103.
|
2013-12-20 03:53:13 +00:00
|
|
|
FST-01 (Flying Stone Tiny 01) is available for sale, and it is a
|
|
|
|
kind of the best choice, hopefully.
|
2011-05-11 02:50:00 +00:00
|
|
|
|
|
|
|
Q4: What's version of GnuPG are you using?
|
2013-12-20 03:53:13 +00:00
|
|
|
A4: In Debian GNU/Linux system, I use gnupg 1.4.12-7 and gnupg-agent
|
|
|
|
2.0.20-1.
|
2011-05-11 02:50:00 +00:00
|
|
|
|
|
|
|
Q5: What's version of pcscd and libccid are you using?
|
2013-12-20 03:53:13 +00:00
|
|
|
A5: I don't use them, pcscd and libccid are optional, you can use Gnuk
|
|
|
|
without them.
|
|
|
|
I tested pcscd 1.5.5-4 and libccid 1.3.11-2 which were in Debian
|
|
|
|
squeeze.
|
2011-05-11 02:50:00 +00:00
|
|
|
|
|
|
|
Q6: What kinds of hardware is required for development?
|
2012-08-03 02:20:13 +00:00
|
|
|
A6: You need a target board plus a JTAG/SWD debugger. If you just
|
|
|
|
want to test Gnuk for target boards with DfuSe, JTAG debugger is
|
|
|
|
not the requirement. Note that for real use, you need JTAG/SWD
|
|
|
|
debugger to enable flash ROM protection.
|
2010-09-10 01:52:07 +00:00
|
|
|
|
2011-05-13 02:59:05 +00:00
|
|
|
Q7: How much does it cost?
|
|
|
|
A7: Olimex STM32-H103 plus ARM-USB-TINY-H cost 70 Euro or so.
|
|
|
|
|
|
|
|
Q9: I got an error like "gpg: selecting openpgp failed: ec=6.108", what's up?
|
|
|
|
A9: GnuPG's SCDaemon has problems for handling insertion/removal of
|
2013-12-20 03:53:13 +00:00
|
|
|
card/reader. When your newly inserted token is not found by
|
|
|
|
GnuPG, try killing scdaemon and let it to be invoked again. I do:
|
2012-07-20 04:04:39 +00:00
|
|
|
|
|
|
|
$ gpg-connect-agent "SCD KILLSCD" "SCD BYE" /bye
|
|
|
|
|
2011-05-13 02:59:05 +00:00
|
|
|
and confirm scdaemon doesn't exist, then,
|
2012-07-20 04:04:39 +00:00
|
|
|
|
|
|
|
$ gpg-connect-agent learn /bye
|
2011-05-13 02:59:05 +00:00
|
|
|
|
2012-05-15 01:16:25 +00:00
|
|
|
Qa: With GNOME 2, I can't use Gnuk Token for SSH. How can we use it for SSH?
|
2011-11-24 06:40:38 +00:00
|
|
|
Aa: You need to deactivate seahorse-agent and gnome-keyring, but use
|
|
|
|
gpg-agant for the role of ssh-agent. For gnome-keyring please do:
|
|
|
|
|
2011-12-13 05:25:07 +00:00
|
|
|
$ gconftool-2 --type bool --set /apps/gnome-keyring/daemon-components/ssh false
|
2011-11-24 06:40:38 +00:00
|
|
|
|
2014-12-13 12:57:38 +00:00
|
|
|
Qb: With GNOME 3.0, I can't use Gnuk Token at all. Why?
|
2011-11-24 06:40:38 +00:00
|
|
|
Ab: That's because gnome-keyring-daemon interferes GnuPG. Type:
|
|
|
|
|
2011-12-13 05:25:07 +00:00
|
|
|
$ gnome-session-properties
|
2011-11-24 06:40:38 +00:00
|
|
|
|
2011-12-13 05:25:07 +00:00
|
|
|
and at the tab of "Startup Programs", disable check buttons for
|
|
|
|
"GPG Password Agent" and "SSH Key Agent".
|
2011-11-24 06:40:38 +00:00
|
|
|
|
2015-07-21 00:25:06 +00:00
|
|
|
Qc: With GNOME 3.x (x >= 8?), I can't use Gnuk Token at all. Why?
|
|
|
|
Ac: That's because gnome-keyring-daemon interferes GnuPG. Please
|
|
|
|
disable the invocation of gnome-keyring-daemon. In Debian
|
|
|
|
wheezy, it's in the files /etc/xdg/autostart/gnome-keyring-ssh.desktop
|
|
|
|
and /etc/xdg/autostart/gnome-keyring-gpg.desktop.
|
|
|
|
We have a line something like:
|
2011-11-24 06:40:38 +00:00
|
|
|
|
2015-07-21 00:25:06 +00:00
|
|
|
OnlyShowIn=GNOME;Unity;MATE;
|
2014-12-13 12:57:38 +00:00
|
|
|
|
2015-07-21 00:25:06 +00:00
|
|
|
Please edit this line to:
|
2014-12-13 12:57:38 +00:00
|
|
|
|
2015-07-21 00:25:06 +00:00
|
|
|
OnlyShowIn=
|
|
|
|
|
|
|
|
Qd: Do you know a good SWD debugger to connect FST-01 or something?
|
|
|
|
Ad: ST-Link/V2 is cheap one. We have a tool/stlinkv2.py as flash ROM
|
|
|
|
writer program.
|
2014-12-13 12:57:38 +00:00
|
|
|
|
|
|
|
|
|
|
|
|
2010-08-30 11:02:22 +00:00
|
|
|
|
|
|
|
Release notes
|
|
|
|
=============
|
|
|
|
|
2014-03-07 06:43:05 +00:00
|
|
|
This is third experimental release in version 1.1 series of Gnuk.
|
2012-08-03 02:20:13 +00:00
|
|
|
|
2014-03-07 06:43:05 +00:00
|
|
|
While it is daily use by its developer, some newly introduced features
|
2015-07-21 00:25:06 +00:00
|
|
|
(including ECDSA/EdDSA/ECDH, key generation and firmware upgrade)
|
|
|
|
should be considered experimental. ECDSA/EdDSA/ECDH is really
|
|
|
|
experimental. Further, ECDH on Curve25519 is much experimental. You
|
|
|
|
won't be able to keep using the key, since the key format of GnuPG is
|
|
|
|
not defined and it's subject to change.
|
2011-05-13 02:59:05 +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-10-20 01:20:45 +00:00
|
|
|
* INTERNAL AUTHENTICATE
|
2011-05-13 02:59:05 +00:00
|
|
|
* Changing value of password status bytes (0x00C4): forcesig
|
2011-01-07 07:18:47 +00:00
|
|
|
* Verify with pin pad
|
2011-01-19 06:44:37 +00:00
|
|
|
* Modify with pin pad
|
2012-07-20 04:04:39 +00:00
|
|
|
* Card holder certificate (read)
|
|
|
|
* Removal of keys
|
2012-06-07 01:48:25 +00:00
|
|
|
* Key generation on device side
|
2013-12-13 01:40:51 +00:00
|
|
|
* Overriding key import
|
2011-01-19 06:44:37 +00:00
|
|
|
|
2012-07-20 04:04:39 +00:00
|
|
|
Original features of Gnuk, tested lightly:
|
2012-06-19 01:19:26 +00:00
|
|
|
|
2012-07-20 04:04:39 +00:00
|
|
|
* OpenPGP card serial number setup
|
|
|
|
* Card holder certificate (write by UPDATE BINARY)
|
2012-06-19 01:19:26 +00:00
|
|
|
* Upgrading with "EXTERNAL AUTHENTICATE" by reGNUal
|
|
|
|
|
2010-09-09 08:50:34 +00:00
|
|
|
It is known not-working well:
|
2010-08-30 11:02:22 +00:00
|
|
|
|
2013-12-13 01:40:51 +00:00
|
|
|
* It is known that the combination of libccid 1.4.1 (or newer)
|
|
|
|
with libusb 1.0.8 (or older) has a minor problem. It is
|
|
|
|
rare but it is possible for USB communication to be failed,
|
|
|
|
because of a bug in libusb implementation. Use libusbx
|
|
|
|
1.0.9 or newer, or don't use PC/SC, but use internal CCID
|
|
|
|
driver of GnuPG.
|
2012-06-19 01:19:26 +00:00
|
|
|
|
2011-05-11 02:50:00 +00:00
|
|
|
|
2010-09-05 09:10:54 +00:00
|
|
|
Targets
|
|
|
|
=======
|
2010-08-30 11:02:22 +00:00
|
|
|
|
2014-12-12 06:39:15 +00:00
|
|
|
We use Olimex STM32-H103 board and Flying Stone Tiny 01 (FST-01).
|
2010-11-30 01:04:30 +00:00
|
|
|
|
2013-12-13 01:40:51 +00:00
|
|
|
With DfuSe support, STBee is also our targets. But this target with
|
|
|
|
DfuSe is for experiment only, because it is impossible for DfuSe to
|
2011-01-28 15:00:47 +00:00
|
|
|
disable read from flash. For real use, please consider killing DfuSe
|
2012-06-06 00:05:24 +00:00
|
|
|
and enabling read protection using JTAG debugger.
|
2010-08-30 11:02:22 +00:00
|
|
|
|
2014-12-13 12:57:38 +00:00
|
|
|
For PIN-pad support, I connect a consumer IR receive module to FST-01,
|
|
|
|
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 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-19 06:44:37 +00:00
|
|
|
|
2012-06-06 00:05:24 +00:00
|
|
|
Note that you need pinpad support for GnuPG to use PIN-pad enabled
|
2013-12-20 03:53:13 +00:00
|
|
|
Gnuk. The pinpad support for GnuPG is only available in version 2.
|
2011-12-14 03:50:54 +00:00
|
|
|
|
2010-08-30 11:02:22 +00:00
|
|
|
|
2015-07-27 09:55:10 +00:00
|
|
|
Build system and Host system
|
|
|
|
============================
|
|
|
|
|
|
|
|
Makefile is written for GNU make. You need Bash 4.x for configure.
|
|
|
|
|
|
|
|
If your bash is not installed as /bin/bash, you need to run configure
|
|
|
|
script prepending 'bash' before './configure'.
|
|
|
|
|
|
|
|
Some tools are written in Python. If your Python is not installed as
|
|
|
|
/usr/bin/python, please prepend 'python' for your command invocation.
|
|
|
|
Python 2.7 and PyUSB 0.4.3 is assumed.
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
2012-06-13 23:46:59 +00:00
|
|
|
Note that SHA-2 hash function implementation, src/sha256.c, is based
|
|
|
|
on the original implementation by Dr. Brian Gladman. See:
|
|
|
|
|
|
|
|
http://gladman.plushost.co.uk/oldsite/cryptography_technology/sha/index.php
|
|
|
|
|
2010-08-30 11:02:22 +00:00
|
|
|
|
|
|
|
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.
|
2012-06-13 23:46:59 +00:00
|
|
|
Please read relevant licenses for external source code as well.
|
2010-09-13 02:47:21 +00:00
|
|
|
|
|
|
|
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
|
2013-12-20 03:53:13 +00:00
|
|
|
if needed. This doesn't mean person who has a Gnuk Token should be
|
|
|
|
able to access everything on the Token, regardless of its protections.
|
|
|
|
Private keys, 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.
|
|
|
|
|
2015-07-21 00:25:06 +00:00
|
|
|
* chopstx/ -- Chopstx 0.07
|
2013-03-19 06:59:00 +00:00
|
|
|
|
2013-12-13 01:40:51 +00:00
|
|
|
We use Chopstx as the kernel for Gnuk.
|
2010-09-05 09:10:54 +00:00
|
|
|
|
2013-12-13 01:40:51 +00:00
|
|
|
Chopstx is distributed under GPLv3+ (with a special exception).
|
2010-08-10 03:11:02 +00:00
|
|
|
|
2013-03-19 07:11:51 +00:00
|
|
|
|
2015-07-21 00:25:06 +00:00
|
|
|
* polarssl/ -- based on PolarSSL 1.2.10 (now mbedTLS)
|
2013-03-19 06:59:00 +00:00
|
|
|
|
|
|
|
Souce code taken from: http://polarssl.org/
|
|
|
|
|
2013-03-19 07:11:51 +00:00
|
|
|
We use PolarSSL for RSA computation, and AES encryption/decryption.
|
|
|
|
|
|
|
|
PolarSSL is distributed under GPLv2+. We use PolarSSL under GPLv3
|
|
|
|
as our options.
|
2010-08-30 11:02:22 +00:00
|
|
|
|
2011-06-14 23:52:02 +00:00
|
|
|
The file include/polarssl/bn_mul.h is heavily modified for ARM
|
|
|
|
Cortex-M3.
|
|
|
|
|
2013-03-19 06:59:00 +00:00
|
|
|
The function rsa_private in polarssl/library/rsa.c is modified so
|
|
|
|
that it doesn't check T against N. The function rsa_pkcs1_sign is
|
|
|
|
modified to avoid warnings in case of !POLARSSL_PKCS1_V21.
|
|
|
|
|
|
|
|
The functions rsa_pkcs1_verify and rsa_rsassa_pkcs1_v15_verify in
|
|
|
|
include/polarssl/rsa.h and polarssl/library/rsa.c are modified
|
|
|
|
(fixed) for last argument SIG, as the memory at SIG aren't modified
|
|
|
|
by those routines.
|
|
|
|
|
|
|
|
The constant POLARSSL_MPI_MAX_SIZE in include/polarssl/bignum.h is
|
|
|
|
modified for 2048-bit keys only Gnuk.
|
2012-06-07 01:39:48 +00:00
|
|
|
|
2013-03-19 06:59:00 +00:00
|
|
|
The function mpi_mul_hlp in library/bignum.c is modified for more
|
2013-12-13 01:40:51 +00:00
|
|
|
optimization for ARM Cortex-M3. Functions mpi_montred, mpi_sub_hlp,
|
2013-12-20 03:53:13 +00:00
|
|
|
mpi_sub_abs, mpi_mul_mpi, mpi_montmul, and mpi_exp_mod are modified
|
2013-12-13 01:40:51 +00:00
|
|
|
to avoid side channel attacks. Note that we don't use RSA-blinding
|
|
|
|
technique for Gnuk. Function mpi_gen_prime and mpi_is_prime are
|
2013-12-20 03:53:13 +00:00
|
|
|
modified to use Fouque-Tibouchi method. Function mpi_exp_mod is
|
|
|
|
modified to use new function mpi_montsqr for speed up.
|
2012-06-07 01:39:48 +00:00
|
|
|
|
2012-05-30 09:50:22 +00:00
|
|
|
The file library/aes.c is modified so that some constants can
|
|
|
|
go to .sys section.
|
|
|
|
|
2013-03-19 07:11:51 +00:00
|
|
|
The file include/polarssl/config.h are modified not to define
|
|
|
|
POLARSSL_HAVE_LONGLONG to avoid linking libgcc, to define
|
|
|
|
POLARSSL_AES_ROM_TABLES to have AES tables, not to define
|
|
|
|
POLARSSL_CIPHER_MODE_CTR, POLARSSL_FS_IO, POLARSSL_PKCS1_V21,
|
|
|
|
POLARSSL_SELF_TEST, and POLARSSL_PADLOCK_C, and only define
|
|
|
|
POLARSSL_GENPRIME when defined KEYGEN_SUPPORT.
|
|
|
|
|
2010-08-18 05:21:58 +00:00
|
|
|
|
2012-05-11 05:09:14 +00:00
|
|
|
USB vendor ID and product ID (USB device ID)
|
|
|
|
============================================
|
|
|
|
|
2012-05-14 02:57:34 +00:00
|
|
|
When you have a vender ID and assign a product ID for Gnuk, edit the
|
|
|
|
file GNUK_USB_DEVICE_ID and add an entry for yours. In this case,
|
|
|
|
please contact Niibe, so that it is listed to the file in the official
|
2012-05-17 03:45:51 +00:00
|
|
|
release of the source code.
|
2012-05-11 05:09:14 +00:00
|
|
|
|
2012-05-14 02:57:34 +00:00
|
|
|
When you are modifing Gnuk and installing the binary to device, you
|
2013-09-25 04:21:13 +00:00
|
|
|
should replace the vendor string and serial number to yours (in the
|
|
|
|
file GNUK_USB_DEVICE_ID and SERIALNO of the script of src/configure),
|
|
|
|
so that users can see it's not by original vendor, and it is modified
|
|
|
|
version.
|
2012-05-11 05:09:14 +00:00
|
|
|
|
|
|
|
FSIJ allows you to use USB device ID of FSIJ (234b:0000) for devices
|
|
|
|
with Gnuk under one of following conditions:
|
|
|
|
|
2012-05-14 02:57:34 +00:00
|
|
|
* For everyone for experimental purpose:
|
2012-05-11 05:09:14 +00:00
|
|
|
|
|
|
|
- You must not distribute a binary with FSIJ's USB device ID, but
|
|
|
|
must use the binary by yourself only for your experiment. Note
|
|
|
|
that "Distributing binary" includes distributing a device which
|
|
|
|
holds the binary.
|
|
|
|
|
|
|
|
* For general individuals:
|
|
|
|
|
2012-05-14 02:57:34 +00:00
|
|
|
- You must use your Gnuk device with a card serial number which is
|
|
|
|
*not* by FSIJ. Easy one would be a card serial number generated
|
|
|
|
by chip unique ID.
|
2012-05-11 05:09:14 +00:00
|
|
|
|
|
|
|
* For individuals with explicit permission from FSIJ.
|
|
|
|
|
|
|
|
- You should have an assigned card serial number by FSIJ,
|
|
|
|
please use that number for your device.
|
|
|
|
(There a file 'GNUK_SERIAL_NUMBER' in the official release.)
|
|
|
|
|
2012-05-17 03:45:51 +00:00
|
|
|
FSIJ could give companies or business entities "second source
|
|
|
|
manufacturer" license to use USB device ID of FSIJ for devices with
|
|
|
|
unmodified version of Gnuk, provided they support Free Software and
|
|
|
|
respect users' freedom for computing. Please ask FSIJ for the
|
|
|
|
license.
|
2012-05-11 05:09:14 +00:00
|
|
|
|
|
|
|
Otherwise, companies which want to distribute Gnuk devices, please use
|
2012-10-12 23:40:37 +00:00
|
|
|
your own USB vendor ID and product ID. Please replace vendor string
|
|
|
|
and possibly product string to yours, when you modify Gnuk.
|
2012-05-11 05:09:14 +00:00
|
|
|
|
|
|
|
|
2010-09-09 16:25:44 +00:00
|
|
|
Host Requirements
|
|
|
|
=================
|
|
|
|
|
2012-07-20 04:04:39 +00:00
|
|
|
For GNU/Linux, PC/SC service is an option, you can use GnuPG's
|
|
|
|
internal CCID driver instead. If you chose using PC/SC service,
|
|
|
|
libccid version >= 1.3.11 is recommended for GNU/Linux.
|
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
|
|
|
|
2013-12-13 01:40:51 +00:00
|
|
|
There is "gcc-arm-embedded" project. See:
|
2012-07-20 04:12:51 +00:00
|
|
|
|
|
|
|
https://launchpad.net/gcc-arm-embedded/
|
|
|
|
|
2010-08-30 11:02:22 +00:00
|
|
|
|
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
|
|
|
|
2012-05-14 02:57:34 +00:00
|
|
|
$ ./configure --vidpid=<VID:PID>
|
|
|
|
|
|
|
|
Here, you need to specify USB vendor ID and product ID. For FSIJ's,
|
2012-05-15 01:16:25 +00:00
|
|
|
it's: --vidpid=234b:0000 . Please read section 'USB vendor ID and
|
|
|
|
product ID' above.
|
2010-09-05 09:10:54 +00:00
|
|
|
|
2015-07-27 09:55:10 +00:00
|
|
|
|
|
|
|
Then, type:
|
2010-09-05 09:10:54 +00:00
|
|
|
|
2010-08-30 11:02:22 +00:00
|
|
|
$ make
|
|
|
|
|
2013-12-13 01:40:51 +00:00
|
|
|
Then, we will have "gnuk.elf" under src/build directory.
|
2010-08-30 11:02:22 +00:00
|
|
|
|
|
|
|
|
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:
|
|
|
|
|
2014-12-12 06:00:51 +00:00
|
|
|
$ openocd -f interface/ftdi/olimex-jtag-tiny.cfg -f board/olimex_stm32_h103.cfg
|
2010-08-30 11:02:22 +00:00
|
|
|
|
|
|
|
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-11-14 05:34:51 +00:00
|
|
|
Flying Stone Tiny 01
|
|
|
|
--------------------
|
|
|
|
|
2014-12-13 12:57:38 +00:00
|
|
|
If you are using Flying Stone Tiny 01, you need a SWD writer.
|
2011-11-14 05:34:51 +00:00
|
|
|
|
2015-07-21 00:25:06 +00:00
|
|
|
OpenOCD 0.9 now supports ST-Link/V2. We can use it:
|
2013-03-15 01:41:18 +00:00
|
|
|
|
|
|
|
$ openocd -f interface/stlink-v2.cfg -f target/stm32f1x_stlink.cfg
|
|
|
|
|
2011-11-14 05:34:51 +00:00
|
|
|
|
|
|
|
|
2013-12-13 01:40:51 +00:00
|
|
|
STBee
|
|
|
|
-----
|
2010-11-02 03:37:13 +00:00
|
|
|
|
|
|
|
Reset the board with "USER" switch pushed. Type following to write
|
|
|
|
to flash:
|
|
|
|
|
|
|
|
# cd ../tool
|
2013-12-13 01:40:51 +00:00
|
|
|
# ./dfuse.py ../src/build/gnuk.hex
|
2010-11-02 03:37:13 +00:00
|
|
|
|
|
|
|
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
|
2013-12-13 01:40:51 +00:00
|
|
|
> stm32f1x lock 0
|
2011-02-10 04:57:23 +00:00
|
|
|
> 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
|
|
|
|
================
|
|
|
|
|
2011-05-11 07:48:08 +00:00
|
|
|
You need python and pyscard (python-pyscard package in Debian) or
|
2014-03-07 06:43:05 +00:00
|
|
|
PyUSB 0.4.3 (python-usb package in Debian).
|
2011-02-10 04:57:23 +00:00
|
|
|
|
2011-10-06 08:02:37 +00:00
|
|
|
(1) [pyscard] Stop scdaemon
|
2011-05-11 07:48:08 +00:00
|
|
|
[PyUSB] Stop the pcsc daemon.
|
|
|
|
|
|
|
|
If scdaemon is running, please kill it, or you will get "Smartcard
|
|
|
|
Exception" by "Sharing violation".
|
|
|
|
|
2012-07-02 08:26:49 +00:00
|
|
|
$ gpg-connect-agent "SCD KILLSCD" "SCD BYE" /bye
|
2011-05-11 07:48:08 +00:00
|
|
|
|
|
|
|
In case of PyUSB tool, you need to stop pcscd.
|
2011-02-10 04:57:23 +00:00
|
|
|
|
|
|
|
# /etc/init.d/pcscd stop
|
|
|
|
|
2011-05-11 07:48:08 +00:00
|
|
|
|
2011-10-06 08:02:37 +00:00
|
|
|
(2) [Optional] Write fixed serial number
|
2011-02-10 04:57:23 +00:00
|
|
|
|
|
|
|
If you use fixed serial number in the file 'GNUK_SERIAL_NUMBER', you can do:
|
|
|
|
|
2015-07-27 09:55:10 +00:00
|
|
|
$ EMAIL=<YOUR-EMAIL-ADDRESS> ../tool/gnuk_put_binary_usb.py -s ../GNUK_SERIAL_NUMBER
|
2011-02-24 06:54:40 +00:00
|
|
|
Writing serial number
|
|
|
|
...
|
2011-02-10 04:57:23 +00:00
|
|
|
|
2011-10-06 08:02:37 +00:00
|
|
|
(3) [Optional] Write card holder certificate
|
2011-02-10 04:57:23 +00:00
|
|
|
|
|
|
|
If you have card holder certificate binary file, you can do:
|
|
|
|
|
2015-07-27 09:55:10 +00:00
|
|
|
$ ../tool/gnuk_put_binary_usb.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
|
|
|
|
|
|
|
Testing Gnuk
|
|
|
|
------------
|
|
|
|
|
2012-07-06 01:21:58 +00:00
|
|
|
Type following command to see Gnuk runs:
|
2010-09-05 09:10:54 +00:00
|
|
|
|
|
|
|
$ gpg --card-status
|
|
|
|
|
|
|
|
|
2013-12-20 03:53:13 +00:00
|
|
|
Besides, there is a functionality test under test/ directory. See
|
2012-07-06 01:21:58 +00:00
|
|
|
test/README.
|
|
|
|
|
|
|
|
|
2013-12-20 03:53:13 +00:00
|
|
|
Personalize the Token, import keys, and change the password
|
|
|
|
-----------------------------------------------------------
|
2011-05-13 02:59:05 +00:00
|
|
|
|
|
|
|
You can personalize the token, putting your information like: Name,
|
2013-12-20 03:53:13 +00:00
|
|
|
Login name, Sex, Languages, URL. To do so, GnuPG command is:
|
2011-05-13 02:59:05 +00:00
|
|
|
|
|
|
|
$ gpg --card-edit
|
|
|
|
|
|
|
|
Note that the factory setting of user password is "123456" and admin
|
|
|
|
password is "12345678" as the specification.
|
|
|
|
|
2012-06-07 01:48:25 +00:00
|
|
|
It is recommended to create your keys on your computer, and import
|
|
|
|
them to Gnuk Token. After you create your keys (they must be 2048-bit
|
|
|
|
RSA), you can import them.
|
|
|
|
|
|
|
|
Gnuk supports key generation, but this feature is young and should be
|
|
|
|
considered experimental.
|
2011-05-13 02:59:05 +00:00
|
|
|
|
2013-12-20 05:06:48 +00:00
|
|
|
For detail, please see documentation under doc/. You can see the HTML
|
|
|
|
version at: http://www.fsij.org/doc-gnuk/
|
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
|
|
|
|
|
|
|
|
|
2012-06-06 00:05:24 +00:00
|
|
|
Firmware update
|
|
|
|
===============
|
|
|
|
|
2012-07-20 23:32:53 +00:00
|
|
|
See doc/note/firmware-update.
|
2012-06-06 00:05:24 +00:00
|
|
|
|
|
|
|
|
2013-02-13 05:23:24 +00:00
|
|
|
Git Repositories
|
|
|
|
================
|
2010-09-10 07:41:00 +00:00
|
|
|
|
2015-03-31 05:05:52 +00:00
|
|
|
Please use: https://anonscm.debian.org/cgit/gnuk/gnuk/
|
2011-05-11 07:48:08 +00:00
|
|
|
|
2013-12-23 07:42:53 +00:00
|
|
|
You can get it by:
|
|
|
|
|
2015-03-12 05:52:41 +00:00
|
|
|
$ git clone git://anonscm.debian.org/gnuk/gnuk/gnuk.git
|
2013-12-23 07:42:53 +00:00
|
|
|
|
2013-12-20 03:53:13 +00:00
|
|
|
It's also available at: www.gniibe.org
|
2014-12-13 12:57:38 +00:00
|
|
|
You can browse at: http://git.gniibe.org/gitweb?p=gnuk/gnuk.git;a=summary
|
2010-09-10 07:41:00 +00:00
|
|
|
|
2013-12-23 07:42:53 +00:00
|
|
|
I put Chopstx as a submodule of Git. Please do this:
|
|
|
|
|
|
|
|
$ git submodule init
|
|
|
|
$ git submodule update
|
|
|
|
|
|
|
|
We have migrated from ChibiOS/RT to Chopstx. If you have old code of
|
2013-12-20 03:53:13 +00:00
|
|
|
ChibiOS/RT, you need:
|
2010-09-10 07:41:00 +00:00
|
|
|
|
2013-12-20 03:53:13 +00:00
|
|
|
Edit .git/config to remove chibios reference
|
|
|
|
git rm --cached chibios
|
2013-02-13 05:23:24 +00:00
|
|
|
|
2011-05-11 07:48:08 +00:00
|
|
|
|
2010-09-10 07:41:00 +00:00
|
|
|
Information on the Web
|
|
|
|
======================
|
|
|
|
|
2011-05-13 02:59:05 +00:00
|
|
|
Please visit: http://www.fsij.org/gnuk/
|
2010-09-10 07:41:00 +00:00
|
|
|
|
2015-03-31 05:05:52 +00:00
|
|
|
Please see the FST-01 support pages:
|
|
|
|
|
|
|
|
http://www.gniibe.org/category/fst-01.html
|
|
|
|
|
|
|
|
Please consider to join Gnuk-users mailing list:
|
|
|
|
|
|
|
|
https://lists.alioth.debian.org/mailman/listinfo/gnuk-users
|
|
|
|
|
2010-09-10 07:41:00 +00:00
|
|
|
|
|
|
|
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
|
|
|
|
==========
|
2015-03-31 05:05:52 +00:00
|
|
|
|
2010-09-13 02:47:21 +00:00
|
|
|
* NUK(R) is a registered trademark owend by MAPA GmbH, Germany.
|
2010-08-30 11:02:22 +00:00
|
|
|
--
|