deon/gnuk
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

doc update

Browse Source
This commit is contained in:
NIIBE Yutaka
2016-06-21 14:44:51 +09:00
parent eabcec107e
commit 691e16c605
15 changed files with 339 additions and 397 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
doc/development.rst
View File

@@ -22,24 +22,19 @@ tool/stlinkv2.py.
OpenOCD
-------
For JTAG/SWD debugger, we can use OpenOCD somehow.
Note that ST-Link/V2 was *not* supported by OpenOCD 0.5.0.
It is supported by version 0.6 or later somehow, but still, you can't
enable protection of flash ROM with OpenOCD using ST-Link/V2.
For JTAG/SWD debugger, we can use OpenOCD.
GNU Toolchain
-------------
You need GNU toolchain and newlib for 'arm-none-eabi' target.
In Debian, we can just apt-get packages of: gcc-arm-none-eabi, binutils-arm-none-eabi, gdb-arm-none-eabi and libnewlib-arm-none-eabi.
There is "gcc-arm-embedded" project. See:
For other distributiions, there is "gcc-arm-embedded" project. See:
https://launchpad.net/gcc-arm-embedded/
It is based on GCC 4.8 (as of December, 2013). We are using "-O3 -Os"
for compiler option.
We are using "-O3 -Os" for compiler option.
Building Gnuk

160
doc/generating-2048-RSA-key.rst
View File

@@ -9,31 +9,31 @@ Key length of RSA
=================
In 2005, NIST (National Institute of Standards and Technology, USA)
has issued the first revision of NIST Special Publication 800-57,
issued the first revision of NIST Special Publication 800-57,
"Recommendation for Key Management".
In 800-57, NIST advises that 1024-bit RSA keys will no longer be
viable after 2010 and advises moving to 2048-bit RSA keys. NIST
advises that 2048-bit keys should be viable until 2030.
As of 2010, GnuPG's default for generating RSA key is 2048-bit.
As of 2016, GnuPG's default for generating RSA key is 2048-bit.
Some people have preference on RSA 4096-bit keys, considering
"longer is better".
However, "longer is better" is not always true. When it's long, it
requires more computational resource, memory and storage, and it
consumes more power for nomal usages. These days, many people has
requires more computational resource, memory, and storage. Further,
it consumes more power for nomal usages. These days, many people has
enough computational resource, that would be true, but less is better
for power consumption.
for power consumption, isn't it?
For security, the key length is just a single factor. We had and will have
algorithm issues, too. It is true that it's difficult to update
our public keys, but this problem wouldn't be solved by just have
our public keys, but this problem wouldn't be solved by just having
longer keys.
We deliberately support only RSA 2048-bit keys for Gnuk, considering
device computation power and host software constraints.
We deliberately recommend use of RSA 2048-bit keys for Gnuk,
considering device computation power and host software constraints.
Thus, the key size is 2048-bit in the examples below.
@@ -43,94 +43,38 @@ Generating keys on host PC
Here is the example session to generate main key and a subkey for encryption.
I invoke GnuPG with ``--gen-key`` option. ::
I invoke GnuPG with ``--quick-gen-key`` option. ::
$ gpg --gen-key
gpg (GnuPG) 1.4.11; Copyright (C) 2010 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
and GnuPG asks kind of key. Select ``RSA and RSA``. ::
Please select what kind of key you want:
(1) RSA and RSA (default)
(2) DSA and Elgamal
(3) DSA (sign only)
(4) RSA (sign only)
Your selection? 1
RSA keys may be between 1024 and 4096 bits long.
and select 2048-bit (as Gnuk Token only supports this). ::
What keysize do you want? (2048)
Requested keysize is 2048 bits
and select expiration of the key. ::
Please specify how long the key should be valid.
0 = key does not expire
<n> = key expires in n days
<n>w = key expires in n weeks
<n>m = key expires in n months
<n>y = key expires in n years
Key is valid for? (0) 0
Key does not expire at all
Confirm key types, bitsize and expiration. ::
Is this correct? (y/N) y
Then enter user ID. ::
You need a user ID to identify your key; the software constructs the user ID
from the Real Name, Comment and Email Address in this form:
"Heinrich Heine (Der Dichter) <heinrichh@duesseldorf.de>"
Real name: Niibe Yutaka
Email address: gniibe@fsij.org
Comment:
You selected this USER-ID:
$ gpg --quick-gen-key "Niibe Yutaka <gniibe@fsij.org>"
About to create a key for:
"Niibe Yutaka <gniibe@fsij.org>"
Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o
and enter passphrase for this **key on host PC**.
Continue? (Y/n) y
It askes passphrase for this **key on host PC**.
Note that this is a passphrase for the key on host PC.
It is different thing to the passphrase of Gnuk Token.
We enter two same inputs two times
(once for passphrase input, and another for confirmation). ::
You need a Passphrase to protect your secret key.
<PASSWORD-KEY-ON-PC>
(once for passphrase input, and another for confirmation),
<PASSWORD-KEY-ON-PC>.
Then, GnuPG generate keys. It takes some time. ::
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
...+++++
+++++
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
..+++++
Not enough random bytes available. Please do some other work to give
the OS a chance to collect more entropy! (Need 15 more bytes)
...+++++
gpg: key 4CA7BABE marked as ultimately trusted
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
gpg: key 76A9392B02CD15D1 marked as ultimately trusted
gpg: revocation certificate stored as '/home/gniibe.gnupg/openpgp-revocs.d/36CE0B8408CFE5CD07F94ACF76A9392B02CD15D1.rev'
public and secret key created and signed.
gpg: checking the trustdb
gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
pub 2048R/4CA7BABE 2010-10-15
Key fingerprint = 1241 24BD 3B48 62AF 7A0A 42F1 00B4 5EBD 4CA7 BABE
uid Niibe Yutaka <gniibe@fsij.org>
sub 2048R/084239CF 2010-10-15
$
gpg: marginals needed: 3 completes needed: 1 trust model: pgp
gpg: depth: 0 valid: 1 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 1u
pub rsa2048 2016-06-20 [S]
36CE0B8408CFE5CD07F94ACF76A9392B02CD15D1
uid [ultimate] Niibe Yutaka <gniibe@fsij.org>
sub rsa2048 2016-06-20 []
Done.
@@ -139,16 +83,17 @@ Authentication subkey is not that common,
but very useful (for SSH authentication).
As it is not that common, we need ``--expert`` option for GnuPG. ::
$ gpg --expert --edit-key 4CA7BABE
gpg (GnuPG) 1.4.11; Copyright (C) 2010 Free Software Foundation, Inc.
gpg (GnuPG) 2.1.13; Copyright (C) 2016 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Secret key is available.
pub 2048R/4CA7BABE created: 2010-10-15 expires: never usage: SC
trust: ultimate validity: ultimate
sub 2048R/084239CF created: 2010-10-15 expires: never usage: E
sec rsa2048/76A9392B02CD15D1
created: 2016-06-20 expires: never usage: SC
trust: ultimate validity: ultimate
ssb rsa2048/4BD1EB26F0E607E6
created: 2016-06-20 expires: never usage: E
[ultimate] (1). Niibe Yutaka <gniibe@fsij.org>
gpg>
@@ -157,18 +102,9 @@ Here, it displays that there are main key and a subkey.
It prompts sub-command with ``gpg>`` .
Here, we enter ``addkey`` sub-command.
Then, we enter the passphrase of **key on host PC**.
It's the one we entered above as <PASSWORD-KEY-ON-PC>. ::
gpg> addkey
Key is protected.
You need a passphrase to unlock the secret key for
user: "Niibe Yutaka <gniibe@fsij.org>"
2048-bit RSA key, ID 4CA7BABE, created 2010-10-15
<PASSWORD-KEY-ON-PC>
gpg: gpg-agent is not available in this session
GnuPG asks kind of key. We select ``RSA (set your own capabilities)``. ::
Please select what kind of key you want:
@@ -178,6 +114,10 @@ GnuPG asks kind of key. We select ``RSA (set your own capabilities)``. ::
(6) RSA (encrypt only)
(7) DSA (set your own capabilities)
(8) RSA (set your own capabilities)
(10) ECC (sign only)
(11) ECC (set your own capabilities)
(12) ECC (encrypt only)
(13) Existing key
Your selection? 8
And select ``Authenticate`` for the capabilities for this key.
@@ -245,24 +185,28 @@ Then, we confirm that we really create the key. ::
Is this correct? (y/N) y
Really create? (y/N) y
Then, it askes the passphrase, it is the passphrase of **key on host PC**.
It's the one we entered above as <PASSWORD-KEY-ON-PC>.
Then, GnuPG generate the key. ::
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
.......+++++
+++++
pub 2048R/4CA7BABE created: 2010-10-15 expires: never usage: SC
trust: ultimate validity: ultimate
sub 2048R/084239CF created: 2010-10-15 expires: never usage: E
sub 2048R/5BB065DC created: 2010-10-22 expires: never usage: A
sec rsa2048/76A9392B02CD15D1
created: 2016-06-20 expires: never usage: SC
trust: ultimate validity: ultimate
ssb rsa2048/4BD1EB26F0E607E6
created: 2016-06-20 expires: never usage: E
ssb rsa2048/F3BA52C64012198D
created: 2016-06-20 expires: never usage: A
[ultimate] (1). Niibe Yutaka <gniibe@fsij.org>
gpg>
We save the key (to the storage of the host PC. ::
We save the key (to the storage of the host PC). ::
gpg> save
$

42
doc/gnome3-gpg-settings.rst
View File

@@ -1,42 +0,0 @@
===========================================
GnuPG settings for GNOME 3.1x and GNOME 3.0
===========================================
In the section `GnuPG settings`_, I wrote how I disable GNOME-keyrings for SSH.
It was for GNOME 2. The old days was good, we just disabled GNOME-keyrings
interference to SSH and customizing our desktop was easy for GNU and UNIX users.
.. _GnuPG settings: gpg-settings
GNOME keyrings in GNOME 3.1x
============================
In the files /etc/xdg/autostart/gnome-keyring-ssh.desktop
and /etc/xdg/autostart/gnome-keyring-gpg.desktop,
we have a line something like: ::
OnlyShowIn=GNOME;Unity;MATE;
Please edit this line to: ::
OnlyShowIn=
Then, no desktop environment invokes gnome-keyring for ssh and gpg. I think that it is The Right Thing.
GNOME keyrings in GNOME 3.0 by GNOME-SESSION-PROPERTIES
=======================================================
We can't use GNOME configuration tool (like GNOME 2) to disable interference by
GNOME keyrings in GNOME 3.0.
It is GNOME-SESSION-PROPERTIES to disable the interference. Invoking::
$ gnome-session-properties
and at the tab of "Startup Programs", I removed radio check buttons
for "GPG Password Agent" and "SSH Key Agent".
Then, I can use proper gpg-agent for GnuPG Agent Service and SSH Agent Service with Gnuk Token in GNOME 3.0.

2
doc/gnuk-keytocard-noremoval.rst
View File

@@ -22,4 +22,4 @@ Lastly, I quit GnuPG. Note that I **don't** save changes. ::
$
All keys are imported to Gnuk Token now.
Still, secret keys are available on PC.
Still, secret keys are available on PC, too.

176
doc/gnuk-keytocard.rst
View File

@@ -24,31 +24,29 @@ After personalization, I put my keys into the Token.
Here is the session log.
I invoke GnuPG with my key (4ca7babe). ::
I invoke GnuPG with my key (249CB3771750745D5CDD323CE267B052364F028D). ::
$ gpg --edit-key 4ca7babe
gpg (GnuPG) 1.4.11; Copyright (C) 2010 Free Software Foundation, Inc.
$ gpg --edit-key 249CB3771750745D5CDD323CE267B052364F028D
gpg (GnuPG) 2.1.13; Copyright (C) 2016 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Secret key is available.
pub 2048R/4CA7BABE created: 2010-10-15 expires: never usage: SC
trust: ultimate validity: ultimate
sub 2048R/084239CF created: 2010-10-15 expires: never usage: E
sub 2048R/5BB065DC created: 2010-10-22 expires: never usage: A
[ultimate] (1). NIIBE Yutaka <gniibe@fsij.org>
sec ed25519/E267B052364F028D
created: 2015-08-12 expires: never usage: SC
trust: ultimate validity: ultimate
ssb cv25519/850AF040D619F240
created: 2015-08-12 expires: never usage: E
ssb ed25519/5F910521FAA805B1
created: 2015-08-12 expires: never usage: A
[ultimate] (1). NIIBE Yutaka <gniibe@debian.org>
[ultimate] (2) NIIBE Yutaka <gniibe@fsij.org>
gpg>
Then, GnuPG enters its own command interaction mode. The prompt is ``gpg>``.
To enable ``keytocard`` command, I type ``toggle`` command. ::
gpg> toggle
sec 2048R/4CA7BABE created: 2010-10-15 expires: never
ssb 2048R/084239CF created: 2010-10-15 expires: never
ssb 2048R/5BB065DC created: 2010-10-22 expires: never
(1) NIIBE Yutaka <gniibe@fsij.org>
Firstly, I import my primary key into Gnuk Token.
I type ``keytocard`` command, answer ``y`` to confirm keyimport,
@@ -56,135 +54,129 @@ and type ``1`` to say it's signature key. ::
gpg> keytocard
Really move the primary key? (y/N) y
Signature key ....: [none]
Encryption key....: [none]
Authentication key: [none]
Please select where to store the key:
(1) Signature key
(3) Authentication key
Your selection? 1
Then, GnuPG asks two passwords. One is the passphrase of **keys on PC**
and another is the password of **Gnuk Token**. Note that the password of
the token and the password of the keys on PC are different things,
Then, GnuPG asks two kinds of passphrases. One is the passphrase of **keys on PC**
and another is the passphrase of **Gnuk Token**. Note that the passphrase of
the token and the passphrase of the keys on PC are different things,
although they can be same.
Here, I assume that Gnuk Token's admin password of factory setting (12345678).
Here, I assume that Gnuk Token's admin passphrase of factory setting (12345678).
I enter these passwords. ::
I enter these passphrases. ::
You need a passphrase to unlock the secret key for
user: "NIIBE Yutaka <gniibe@fsij.org>"
2048-bit RSA key, ID 4CA7BABE, created 2010-10-15
<PASSWORD-KEY-4CA7BABE>
gpg: writing new key
gpg: 3 Admin PIN attempts remaining before card is permanently locked
Please enter your passphrase, so that the secret key can be unlocked for this session
<PASSWORD-KEY-ON-PC>
Please enter the Admin PIN
Enter Admin PIN: 12345678
sec 2048R/4CA7BABE created: 2010-10-15 expires: never
card-no: F517 00000001
ssb 2048R/084239CF created: 2010-10-15 expires: never
ssb 2048R/5BB065DC created: 2010-10-22 expires: never
(1) NIIBE Yutaka <gniibe@fsij.org>
The primary key is now on the Token and GnuPG says its card-no (F517 00000001),
where F517 is the vendor ID of FSIJ.
sec ed25519/E267B052364F028D
created: 2015-08-12 expires: never usage: SC
trust: ultimate validity: ultimate
ssb cv25519/850AF040D619F240
created: 2015-08-12 expires: never usage: E
ssb ed25519/5F910521FAA805B1
created: 2015-08-12 expires: never usage: A
[ultimate] (1). NIIBE Yutaka <gniibe@fsij.org>
[ultimate] (2) NIIBE Yutaka <gniibe@debian.org>
Secondly, I import my subkey of encryption. I select key number '1'. ::
gpg> key 1
sec 2048R/4CA7BABE created: 2010-10-15 expires: never
card-no: F517 00000001
ssb* 2048R/084239CF created: 2010-10-15 expires: never
ssb 2048R/5BB065DC created: 2010-10-22 expires: never
(1) NIIBE Yutaka <gniibe@fsij.org>
sec ed25519/E267B052364F028D
created: 2015-08-12 expires: never usage: SC
trust: ultimate validity: ultimate
ssb* cv25519/850AF040D619F240
created: 2015-08-12 expires: never usage: E
ssb ed25519/5F910521FAA805B1
created: 2015-08-12 expires: never usage: A
[ultimate] (1). NIIBE Yutaka <gniibe@fsij.org>
[ultimate] (2) NIIBE Yutaka <gniibe@debian.org>
You can see that the subkey is marked by '*'.
I type ``keytocard`` command to import this subkey to Gnuk Token.
I select ``2`` as it's encryption key. ::
gpg> keytocard
Signature key ....: [none]
Encryption key....: [none]
Authentication key: [none]
Please select where to store the key:
(2) Encryption key
Your selection? 2
Then, GnuPG asks the passphrase of **keys on PC** again. I enter. ::
You need a passphrase to unlock the secret key for
user: "NIIBE Yutaka <gniibe@fsij.org>"
2048-bit RSA key, ID 084239CF, created 2010-10-15
<PASSWORD-KEY-4CA7BABE>
gpg: writing new key
Please enter your passphrase, so that the secret key can be unlocked for this session
<PASSWORD-KEY-ON-PC>
sec 2048R/4CA7BABE created: 2010-10-15 expires: never
card-no: F517 00000001
ssb* 2048R/084239CF created: 2010-10-15 expires: never
card-no: F517 00000001
ssb 2048R/5BB065DC created: 2010-10-22 expires: never
(1) NIIBE Yutaka <gniibe@fsij.org>
sec ed25519/E267B052364F028D
created: 2015-08-12 expires: never usage: SC
trust: ultimate validity: ultimate
ssb* cv25519/850AF040D619F240
created: 2015-08-12 expires: never usage: E
ssb ed25519/5F910521FAA805B1
created: 2015-08-12 expires: never usage: A
[ultimate] (1). NIIBE Yutaka <gniibe@fsij.org>
[ultimate] (2) NIIBE Yutaka <gniibe@debian.org>
The sub key is now on the Token.
The sub key is now on the Token and GnuPG says its card-no for it.
I type ``key 1`` to deselect key number '1'. ::
gpg> key 1
sec 2048R/4CA7BABE created: 2010-10-15 expires: never
card-no: F517 00000001
ssb 2048R/084239CF created: 2010-10-15 expires: never
card-no: F517 00000001
ssb 2048R/5BB065DC created: 2010-10-22 expires: never
(1) NIIBE Yutaka <gniibe@fsij.org>
sec ed25519/E267B052364F028D
created: 2015-08-12 expires: never usage: SC
trust: ultimate validity: ultimate
ssb cv25519/850AF040D619F240
created: 2015-08-12 expires: never usage: E
ssb ed25519/5F910521FAA805B1
created: 2015-08-12 expires: never usage: A
[ultimate] (1). NIIBE Yutaka <gniibe@fsij.org>
[ultimate] (2) NIIBE Yutaka <gniibe@debian.org>
Thirdly, I select sub key of authentication which has key number '2'. ::
gpg> key 2
sec 2048R/4CA7BABE created: 2010-10-15 expires: never
card-no: F517 00000001
ssb 2048R/084239CF created: 2010-10-15 expires: never
card-no: F517 00000001
ssb* 2048R/5BB065DC created: 2010-10-22 expires: never
(1) NIIBE Yutaka <gniibe@fsij.org>
sec ed25519/E267B052364F028D
created: 2015-08-12 expires: never usage: SC
trust: ultimate validity: ultimate
ssb cv25519/850AF040D619F240
created: 2015-08-12 expires: never usage: E
ssb* ed25519/5F910521FAA805B1
created: 2015-08-12 expires: never usage: A
[ultimate] (1). NIIBE Yutaka <gniibe@fsij.org>
[ultimate] (2) NIIBE Yutaka <gniibe@debian.org>
You can see that the subkey number '2' is marked by '*'.
I type ``keytocard`` command to import this subkey to Gnuk Token.
I select ``3`` as it's authentication key. ::
gpg> keytocard
Signature key ....: [none]
Encryption key....: [none]
Authentication key: [none]
Please select where to store the key:
(3) Authentication key
Your selection? 3
Then, GnuPG asks the passphrase of **keys on PC** again. I enter. ::
You need a passphrase to unlock the secret key for
user: "NIIBE Yutaka <gniibe@fsij.org>"
2048-bit RSA key, ID 5BB065DC, created 2010-10-22
<PASSWORD-KEY-4CA7BABE>
gpg: writing new key
Please enter your passphrase, so that the secret key can be unlocked for this session
<PASSWORD-KEY-ON-PC>
sec 2048R/4CA7BABE created: 2010-10-15 expires: never
card-no: F517 00000001
ssb 2048R/084239CF created: 2010-10-15 expires: never
card-no: F517 00000001
ssb* 2048R/5BB065DC created: 2010-10-22 expires: never
card-no: F517 00000001
(1) NIIBE Yutaka <gniibe@fsij.org>
sec ed25519/E267B052364F028D
created: 2015-08-12 expires: never usage: SC
trust: ultimate validity: ultimate
ssb cv25519/850AF040D619F240
created: 2015-08-12 expires: never usage: E
ssb* ed25519/5F910521FAA805B1
created: 2015-08-12 expires: never usage: A
[ultimate] (1). NIIBE Yutaka <gniibe@fsij.org>
[ultimate] (2) NIIBE Yutaka <gniibe@debian.org>
The sub key is now on the Token and GnuPG says its card-no for it.
The sub key is now on the Token.
Lastly, I save changes of **keys on PC** and quit GnuPG. ::

66
doc/gnuk-passphrase-setting.rst
View File

@@ -22,41 +22,40 @@ Besides, some people sometimes prefer the word "passphrase" to
same thing and it just refer user-password or admin-password.
Set up PW1, PW3 and reset code
==============================
Set up PW1 and PW3
==================
Invoke GnuPG with the option ``--card-edit``. ::
$ gpg --card-edit
Application ID ...: D276000124010200F517000000010000
Reader ...........: 234B:0000:FSIJ-1.2.0-87193059:0
Application ID ...: D276000124010200FFFE871930590000
Version ..........: 2.0
Manufacturer .....: FSIJ
Serial number ....: 00000001
Manufacturer .....: unmanaged S/N range
Serial number ....: 87193059
Name of cardholder: Yutaka Niibe
Language prefs ...: ja
Sex ..............: male
URL of public key : http://www.gniibe.org/gniibe.asc
URL of public key : http://www.gniibe.org/gniibe-20150813.asc
Login data .......: gniibe
Signature PIN ....: not forced
Key attributes ...: 2048R 2048R 2048R
Key attributes ...: ed25519 cv25519 ed25519
Max. PIN lengths .: 127 127 127
PIN retry counter : 3 3 3
Signature counter : 0
Signature key ....: 1241 24BD 3B48 62AF 7A0A 42F1 00B4 5EBD 4CA7 BABE
created ....: 2010-10-15 06:46:33
Encryption key....: 42E1 E805 4E6F 1F30 26F2 DC79 79A7 9093 0842 39CF
created ....: 2010-10-15 06:46:33
Authentication key: B4D9 7142 C42D 6802 F5F7 4E70 9C33 B6BA 5BB0 65DC
created ....: 2010-10-22 06:06:36
General key info..:
pub 2048R/4CA7BABE 2010-10-15 NIIBE Yutaka <gniibe@fsij.org>
sec> 2048R/4CA7BABE created: 2010-10-15 expires: never
card-no: F517 00000001
ssb> 2048R/084239CF created: 2010-10-15 expires: never
card-no: F517 00000001
ssb> 2048R/5BB065DC created: 2010-10-22 expires: never
card-no: F517 00000001
Signature key ....: 249C B377 1750 745D 5CDD 323C E267 B052 364F 028D
created ....: 2015-08-12 07:10:48
Encryption key....: E228 AB42 0F73 3B1D 712D E50C 850A F040 D619 F240
created ....: 2015-08-12 07:10:48
Authentication key: E63F 31E6 F203 20B5 D796 D266 5F91 0521 FAA8 05B1
created ....: 2015-08-12 07:16:14
General key info..: pub ed25519/E267B052364F028D 2015-08-12 NIIBE Yutaka <gniibe@fsij.org>
sec> ed25519/E267B052364F028D created: 2015-08-12 expires: never
card-no: FFFE 87193059
ssb> cv25519/850AF040D619F240 created: 2015-08-12 expires: never
card-no: FFFE 87193059
ssb> ed25519/5F910521FAA805B1 created: 2015-08-12 expires: never
card-no: FFFE 87193059
gpg/card>
It shows the status of the card (as same as the output of ``gpg --card-status``).
@@ -71,7 +70,7 @@ Note that *the length of PIN should be more than (or equals to) 8* for
"admin less mode". ::
gpg/card> passwd
gpg: OpenPGP card no. D276000124010200F517000000010000 detected
gpg: OpenPGP card no. D276000124010200FFFE871930590000 detected
Please enter the PIN
Enter PIN: 123456
@@ -94,15 +93,24 @@ please change admin-password at first.
Then, the token works as same as OpenPGPcard specification
with regards to PW1 and PW3.)
Lastly, I setup reset code, entering admin mode.
Having reset code, you can unblock PIN when the token will be blocked
(by wrong attempt to entering PIN). This is optional step. ::
Set up of reset code (optional)
===============================
Lastly, we can setup reset code, entering admin mode.
Having reset code, we can unblock the token when the token will be blocked
(by wrong attempts to entering passphrase). Note that this is optional step.
When reset code is known to someone, that person can try to guess your passphrase of PW1 more times by unblocking the token. So, I don't use this feature by myself.
If we do, here is the interaction. ::
gpg/card> admin
Admin commands are allowed
gpg/card> passwd
gpg: OpenPGP card no. D276000124010200F517000000010000 detected
gpg: OpenPGP card no. D276000124010200FFFE871930590000 detected
1 - change PIN
2 - unblock PIN
@@ -135,4 +143,4 @@ Then, I quit. ::
gpg/card> quit
That's all.
That's all in this step.

12
doc/gnuk-personalization.rst
View File

@@ -9,17 +9,19 @@ Personalize your Gnuk Token
Invoke GnuPG with the option ``--card-edit``. ::
$ gpg --card-edit
Application ID ...: D276000124010200FFFE330069060000
Reader ...........: 234B:0000:FSIJ-1.2.0-87193059:0
Application ID ...: D276000124010200FFFE871930590000
Version ..........: 2.0
Manufacturer .....: unmanaged S/N range
Serial number ....: 33006906
Serial number ....: 87193059
Name of cardholder: [not set]
Language prefs ...: [not set]
Sex ..............: unspecified
URL of public key : [not set]
Login data .......: [not set]
Signature PIN ....: forced
Key attributes ...: 2048R 2048R 2048R
Key attributes ...: rsa2048 rsa2048 rsa2048
Max. PIN lengths .: 127 127 127
PIN retry counter : 3 3 3
Signature counter : 0
@@ -58,7 +60,7 @@ login, and URL. URL specifies the place where I put my public keys. ::
Sex ((M)ale, (F)emale or space): m
gpg/card> url
URL to retrieve public key: http://www.gniibe.org/gniibe.asc
URL to retrieve public key: http://www.gniibe.org/gniibe-20150813.asc
gpg/card> login
Login data (account name): gniibe
@@ -72,4 +74,4 @@ Then, I quit. ::
gpg/card> quit
That's all.
That's all in this step.

4
doc/gnuk-token-initial-configuration.rst
View File

@@ -27,13 +27,15 @@ Make sure there is no ``scdaemon`` for configuring Gnuk Token. You can kill ``
Serial Number (optional)
========================
Note that this is completely optional step. I don't know anyone other than me, do this. Even for me, I only do that for a single device among multiple devices I use. I do that to test the feature.
In the file ``GNUK_SERIAL_NUMBER``, each line has email and 6-byte serial number. The first two bytes are organization number (F5:17 is for FSIJ). Last four bytes are number for tokens.
The tool ``../tool/gnuk_put_binary_libusb.py`` examines environment variable of ``EMAIL``, and writes corresponding serial number to Gnuk Token. ::
$ ../tool/gnuk_put_binary_libusb.py -s ../GNUK_SERIAL_NUMBER
Writing serial number
Device: 006
Device:
Configuration: 1
Interface: 0
d2 76 00 01 24 01 02 00 f5 17 00 00 00 01 00 00

31
doc/gpg-settings.rst
View File

@@ -12,35 +12,38 @@ Here is my GnuPG settings.
I create ``.gnupg/gpg.conf`` file with the following content. ::
use-agent
personal-digest-preferences SHA256
cert-digest-algo SHA256
default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed
default-key 0xE267B052364F028D
default-key 0x4ca7babe
In addition to the ``use-agent`` option, set preferences on algorithms, and specify my default key.
In addition to the ``use-agent`` option, I specify my default key.
The ``use-agent`` option is for GnuPG 1.4.x and it means using gpg-agent if available.
If no option, GnuPG 1.4.x directly connects to Gnuk Token by itself, instead of through scdaemon. When GnuPG 1.4.x tries to access Gnuk Token and scdaemon is running, there are conflicts.
We recommend to specify the ``use-agent`` option for GnuPG 1.4.x to access Gnuk Token through gpg-agent and scdaemon.
For GnuPG 2.0.x, gpg-agent is always used, so there is no need to specify the ``use-agent`` option, but having this option is no harm, anyway.
For GnuPG 2.0 and 2.1, gpg-agent is always used, so, there is no need to specify the ``use-agent`` option, but having this option is no harm, anyway.
Let gpg-agent manage SSH key
============================
I deactivate seahorse-agent. Also, for GNOME 2, I deactivate gnome-keyring managing SSH key. ::
$ gconftool-2 --type bool --set /apps/gnome-keyring/daemon-components/ssh false
I edit the file /etc/X11/Xsession.options and comment out use-ssh-agent line.
Then, I create ``.gnupg/gpg-agent.conf`` file with the following content. ::
I create ``.gnupg/gpg-agent.conf`` file with the following content. ::
enable-ssh-support
I edit the file /etc/X11/Xsession.options and comment out use-ssh-agent line,
so that Xsession doesn't invoke original ssh-agent. We use gpg-agent as ssh-agent.
In the files /etc/xdg/autostart/gnome-keyring-ssh.desktop,
I have a line something like: ::
OnlyShowIn=GNOME;Unity;MATE;
I edit this line to: ::
OnlyShowIn=
So that no desktop environment enables gnome-keyring for ssh.
References
==========

5
doc/index.rst
View File

@@ -2,8 +2,8 @@
sphinx-quickstart on Wed Jul 4 15:29:05 2012.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Copyright (C) 2012, 2013 NIIBE Yutaka
Copyright (C) 2012, 2013 Free Software Initiative of Japan
Copyright (C) 2012, 2013, 2016 NIIBE Yutaka
Copyright (C) 2012, 2013, 2016 Free Software Initiative of Japan
This document is licensed under a CC-BY-SA 3.0 Unported License
Gnuk Documentation
@@ -25,7 +25,6 @@ Contents:
gnuk-keytocard-noremoval.rst
gnuk-passphrase-setting.rst
using-gnuk-token-with-another-computer.rst
gnome3-gpg-settings.rst
development.rst

8
doc/intro.rst
View File

@@ -31,15 +31,15 @@ Target boards for running Gnuk
------------------------------
Hardware requirement for Gnuk is the micro controller STM32F103.
In version 1.1.x, Gnuk supports following boards.
In version 1.2, Gnuk supports following boards.
* FST-01 (Flying Stone Tiny ZERO-ONE)
* Olimex STM32-H103
* STM32 part of STM8S Discovery Kit
* ST Nucleo F103
* STBee
* Nitrokey Start
Host prerequisites for using Gnuk Token
@@ -49,8 +49,6 @@ Host prerequisites for using Gnuk Token
* libusb
* [Optional] PC/SC lite (pcscd, libccid)
* [Optional] SSH: openssh
* [optional] Web: scute, firefox

8
doc/stop-scdaemon.rst
View File

@@ -28,10 +28,16 @@ To stop SCDAEMON and let it exit, type::
Then, you can confirm that there is no SCDAEMON any more by ``ps``
command.
Or, you can use ``gpgconf`` command. Type::
$ gpgconf --reload scdameon
will do the samething.
Let GPG-AGENT/SCDAEMON learn
============================
To let gpg-agent/scdaemon learn from Gnuk Token, type::
To let gpg-agent/scdaemon "learn" from Gnuk Token, type::
$ gpg-connect-agent learn /bye

13
doc/udev-rules.rst
View File

@@ -10,10 +10,13 @@ PC/SC Lite, as it has its own device configuration.
udev rules for Gnuk Token
=========================
In case of Debian, there is a file /lib/udev/rules.d/60-gnupg.rules,
when you install "gnupg" package. This is the place we need to
change, if your installation is older (than jessie). Newer "gnupg"
package (1.4.15-1 or later) has already supported Gnuk Token.
In case of Debian, there is a file /lib/udev/rules.d/60-gnupg.rules
(or /lib/udev/rules.d/60-scdamon.rules for newer version),
when you install "gnupg" package (or "scdaemon" package).
This is the place we need to
change, if your installation is older than jessie. Newer "gnupg"
package (1.4.15-1 or later) or "scdaemon" package has already
supported Gnuk Token.
If needed, please add lines for Gnuk Token to give a desktop user the
permission to use the device. We specify USB ID of Gnuk Token (by
@@ -30,7 +33,7 @@ FSIJ)::
+
LABEL="gnupg_rules_end"
When we install "gnupg2" package only (with no "gnupg" package),
When we only install "gnupg2" package for 2.0 (with no "gnupg" package),
there will be no udev rules (there is a bug report #543217 for this issue).
In this case, we need something like this in /etc/udev/rules.d/60-gnuk.rules::

191
doc/using-gnuk-token-with-another-computer.rst
View File

@@ -12,90 +12,90 @@ while ``.gnupg`` directory contains keyrings and trustdb, too.
Fetch the public key and connect it to the Token
================================================
Using the Token, we need to put the public key and the secret
key reference (to the token) in ``.gnupg``.
In order to use the Token, we need to put the public key and the secret
key references (to the token) under ``.gnupg`` directory.
To do that, invoke GnuPG with ``--card-edit`` option. ::
$ gpg --card-edit
Application ID ...: D276000124010200F517000000010000
Reader ...........: 234B:0000:FSIJ-1.2.0-87193059:0
Application ID ...: D276000124010200FFFE871930590000
Version ..........: 2.0
Manufacturer .....: FSIJ
Serial number ....: 00000001
Manufacturer .....: unmanaged S/N range
Serial number ....: 87193059
Name of cardholder: Yutaka Niibe
Language prefs ...: ja
Sex ..............: male
URL of public key : http://www.gniibe.org/gniibe.asc
URL of public key : http://www.gniibe.org/gniibe-20150813.asc
Login data .......: gniibe
Signature PIN ....: not forced
Key attributes ...: 2048R 2048R 2048R
Key attributes ...: ed25519 cv25519 ed25519
Max. PIN lengths .: 127 127 127
PIN retry counter : 3 3 3
Signature counter : 6
Signature key ....: 1241 24BD 3B48 62AF 7A0A 42F1 00B4 5EBD 4CA7 BABE
created ....: 2010-10-15 06:46:33
Encryption key....: 42E1 E805 4E6F 1F30 26F2 DC79 79A7 9093 0842 39CF
created ....: 2010-10-15 06:46:33
Authentication key: B4D9 7142 C42D 6802 F5F7 4E70 9C33 B6BA 5BB0 65DC
created ....: 2010-10-22 06:06:36
Signature counter : 0
Signature key ....: 249C B377 1750 745D 5CDD 323C E267 B052 364F 028D
created ....: 2015-08-12 07:10:48
Encryption key....: E228 AB42 0F73 3B1D 712D E50C 850A F040 D619 F240
created ....: 2015-08-12 07:10:48
Authentication key: E63F 31E6 F203 20B5 D796 D266 5F91 0521 FAA8 05B1
created ....: 2015-08-12 07:16:14
General key info..: [none]
gpg/card>
It says, there is no key info related to this token on your PC (``[none]``).
Here, the secret key references (to the token) are created under ``.gnupg/private-keys-v1.d`` directory. It can be also created when I do ``--card-status`` by GnuPG.
Fetch the public key from URL specified in the Token. ::
Still, it says that there is no key info related to this token on my PC (``[none]`` for General key info), because I don't have the public key on this PC yet.
So, I fetch the public key from URL specified in the Token. ::
gpg/card> fetch
gpg: requesting key 4CA7BABE from http server www.gniibe.org
gpg: key 4CA7BABE: public key "NIIBE Yutaka <gniibe@fsij.org>" imported
gpg: no ultimately trusted keys found
gpg: requesting key E267B052364F028D from http server www.gniibe.org
gpg: key E267B052364F028D: public key "NIIBE Yutaka <gniibe@fsij.org>" imported
gpg: Total number processed: 1
gpg: imported: 1 (RSA: 1)
gpg: imported: 1
gpg: marginals needed: 3 completes needed: 1 trust model: pgp
gpg: depth: 0 valid: 6 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 6u
gpg/card>
Good. The public key is now in ``.gnupg``. We can examine by ``gpg --list-keys``.
Good. The public key is now under ``.gnupg`` directory. We can examine by ``gpg --list-keys``.
However, the secret key reference (to the token) is not in ``.gnupg`` yet.
When I type return at the ``gpg/card>`` prompt, now, I can see: ::
It will be generated when I do ``--card-status`` by GnuPG with
correspoinding public key in ``.gnupg``, or just type return
at the ``gpg/card>`` prompt. ::
gpg/card>
Application ID ...: D276000124010200F517000000010000
Reader ...........: 234B:0000:FSIJ-1.2.0-87193059:0
Application ID ...: D276000124010200FFFE871930590000
Version ..........: 2.0
Manufacturer .....: FSIJ
Serial number ....: 00000001
Manufacturer .....: unmanaged S/N range
Serial number ....: 87193059
Name of cardholder: Yutaka Niibe
Language prefs ...: ja
Sex ..............: male
URL of public key : http://www.gniibe.org/gniibe.asc
URL of public key : http://www.gniibe.org/gniibe-20150813.asc
Login data .......: gniibe
Signature PIN ....: not forced
Key attributes ...: 2048R 2048R 2048R
Key attributes ...: ed25519 cv25519 ed25519
Max. PIN lengths .: 127 127 127
PIN retry counter : 3 3 3
Signature counter : 6
Signature key ....: 1241 24BD 3B48 62AF 7A0A 42F1 00B4 5EBD 4CA7 BABE
created ....: 2010-10-15 06:46:33
Encryption key....: 42E1 E805 4E6F 1F30 26F2 DC79 79A7 9093 0842 39CF
created ....: 2010-10-15 06:46:33
Authentication key: B4D9 7142 C42D 6802 F5F7 4E70 9C33 B6BA 5BB0 65DC
created ....: 2010-10-22 06:06:36
General key info..:
pub 2048R/4CA7BABE 2010-10-15 NIIBE Yutaka <gniibe@fsij.org>
sec> 2048R/4CA7BABE created: 2010-10-15 expires: never
card-no: F517 00000001
ssb> 2048R/084239CF created: 2010-10-15 expires: never
card-no: F517 00000001
ssb> 2048R/5BB065DC created: 2010-10-22 expires: never
card-no: F517 00000001
Signature counter : 0
Signature key ....: 249C B377 1750 745D 5CDD 323C E267 B052 364F 028D
created ....: 2015-08-12 07:10:48
Encryption key....: E228 AB42 0F73 3B1D 712D E50C 850A F040 D619 F240
created ....: 2015-08-12 07:10:48
Authentication key: E63F 31E6 F203 20B5 D796 D266 5F91 0521 FAA8 05B1
created ....: 2015-08-12 07:16:14
General key info..: pub ed25519/E267B052364F028D 2015-08-12 NIIBE Yutaka <gniibe@fsij.org>
sec> ed25519/E267B052364F028D created: 2015-08-12 expires: never
card-no: FFFE 87193059
ssb> cv25519/850AF040D619F240 created: 2015-08-12 expires: never
card-no: FFFE 87193059
ssb> ed25519/5F910521FAA805B1 created: 2015-08-12 expires: never
card-no: FFFE 87193059
gpg/card>
Note that, it displays the information about "General key info".
OK, now I can use the Token on this computer.
@@ -103,33 +103,43 @@ Update trustdb for the key on Gnuk Token
========================================
Yes, I can use the Token by the public key and the secret
key reference to the card. More, I need to update the trustdb.
key references to the card. More, I need to update the trustdb.
To do that I do: ::
To do that, I do: ::
$ gpg --edit-key 4ca7babe
gpg (GnuPG) 1.4.11; Copyright (C) 2010 Free Software Foundation, Inc.
$ ./gpg --edit-key E267B052364F028D
gpg (GnuPG) 2.1.13; Copyright (C) 2016 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Secret key is available.
pub 2048R/4CA7BABE created: 2010-10-15 expires: never usage: SC
trust: unknown validity: unknown
sub 2048R/084239CF created: 2010-10-15 expires: never usage: E
sub 2048R/5BB065DC created: 2010-10-22 expires: never usage: A
sec ed25519/E267B052364F028D
created: 2015-08-12 expires: never usage: SC
card-no: FFFE 87193059
trust: unknown validity: unknown
ssb cv25519/850AF040D619F240
created: 2015-08-12 expires: never usage: E
card-no: FFFE 87193059
ssb ed25519/5F910521FAA805B1
created: 2015-08-12 expires: never usage: A
card-no: FFFE 87193059
[ unknown] (1). NIIBE Yutaka <gniibe@fsij.org>
[ unknown] (2) NIIBE Yutaka <gniibe@debian.org>
gpg>
See, the key is ``unknown`` state. Add trust for that. ::
See, the key is ``unknown`` state. Add trust for that, because it's the key under my control. ::
gpg> trust
pub 2048R/4CA7BABE created: 2010-10-15 expires: never usage: SC
trust: unknown validity: unknown
sub 2048R/084239CF created: 2010-10-15 expires: never usage: E
sub 2048R/5BB065DC created: 2010-10-22 expires: never usage: A
sec ed25519/E267B052364F028D
created: 2015-08-12 expires: never usage: SC
card-no: FFFE 87193059
trust: unknown validity: unknown
ssb cv25519/850AF040D619F240
created: 2015-08-12 expires: never usage: E
card-no: FFFE 87193059
ssb ed25519/5F910521FAA805B1
created: 2015-08-12 expires: never usage: A
card-no: FFFE 87193059
[ unknown] (1). NIIBE Yutaka <gniibe@fsij.org>
[ unknown] (2) NIIBE Yutaka <gniibe@debian.org>
@@ -146,32 +156,49 @@ See, the key is ``unknown`` state. Add trust for that. ::
Your decision? 5
Do you really want to set this key to ultimate trust? (y/N) y
pub 2048R/4CA7BABE created: 2010-10-15 expires: never usage: SC
trust: ultimate validity: unknown
sub 2048R/084239CF created: 2010-10-15 expires: never usage: E
sub 2048R/5BB065DC created: 2010-10-22 expires: never usage: A
sec ed25519/E267B052364F028D
created: 2015-08-12 expires: never usage: SC
card-no: FFFE 87193059
trust: ultimate validity: unknown
ssb cv25519/850AF040D619F240
created: 2015-08-12 expires: never usage: E
card-no: FFFE 87193059
ssb ed25519/5F910521FAA805B1
created: 2015-08-12 expires: never usage: A
card-no: FFFE 87193059
[ unknown] (1). NIIBE Yutaka <gniibe@fsij.org>
[ unknown] (2) NIIBE Yutaka <gniibe@debian.org>
Please note that the shown key validity is not necessarily correct
unless you restart the program.
$
gpg>
Next time I invoke GnuPG, it will be ``ultimate`` key. Let's see: ::
And I quit from gpg. Then, when I invoke GnuPG, it will be ``ultimate`` key. Let's see: ::
$ gpg --edit-key 4ca7babe
gpg (GnuPG) 1.4.11; Copyright (C) 2010 Free Software Foundation, Inc.
$ ./gpg --edit-key E267B052364F028D
gpg (GnuPG) 2.1.13; Copyright (C) 2016 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Secret key is available.
pub 2048R/4CA7BABE created: 2010-10-15 expires: never usage: SC
trust: ultimate validity: ultimate
sub 2048R/084239CF created: 2010-10-15 expires: never usage: E
sub 2048R/5BB065DC created: 2010-10-22 expires: never usage: A
gpg: checking the trustdb
gpg: marginals needed: 3 completes needed: 1 trust model: pgp
gpg: depth: 0 valid: 7 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 7u
sec ed25519/E267B052364F028D
created: 2015-08-12 expires: never usage: SC
card-no: FFFE 87193059
trust: ultimate validity: ultimate
ssb cv25519/850AF040D619F240
created: 2015-08-12 expires: never usage: E
card-no: FFFE 87193059
ssb ed25519/5F910521FAA805B1
created: 2015-08-12 expires: never usage: A
card-no: FFFE 87193059
[ultimate] (1). NIIBE Yutaka <gniibe@fsij.org>
[ultimate] (2) NIIBE Yutaka <gniibe@debian.org>
gpg> quit
$
$
OK, all set. I'm ready to use my Gnuk Token on this PC.