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

Add doc

Browse Source
This commit is contained in:
NIIBE Yutaka
2012-08-03 10:53:04 +09:00
parent 7575dda42a
commit eb0e913eee
10 changed files with 1006 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

228
doc/generating-2048-RSA-key.rst Normal file
View File

@@ -0,0 +1,228 @@
============================
Generating 2048-bit RSA keys
============================
This document describes how I generate 2048-bit RSA keys.
.. BREAK
Here is the log to generate signature key and encryption subkey.
I invoke GnuPG with ``--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 suppurt 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:
"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 PC**. ::
You need a Passphrase to protect your secret key.
<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 28C0CD7C marked as ultimately trusted
public and secret key created and signed.
gpg: checking the trustdb
gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
gpg: depth: 0 valid: 2 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 2u
pub 2048R/28C0CD7C 2011-05-24
Key fingerprint = 0B4D C763 D57B ADBB 1870 A978 BDEE 4A35 28C0 CD7C
uid Niibe Yutaka <gniibe@fsij.org>
sub 2048R/F01E19B7 2011-05-24
$
Done.
Then, I create authentication subkey. Authentication subkey is not that common, but very useful (say, for SSH authentication). As it is not that common, we need ``--expert`` option for GnuPG. ::
$ gpg --expert --edit-key 28C0CD7C
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.
Secret key is available.
pub 2048R/28C0CD7C created: 2011-05-24 expires: never usage: SC
trust: ultimate validity: ultimate
sub 2048R/F01E19B7 created: 2011-05-24 expires: never usage: E
[ultimate] (1). Niibe Yutaka <gniibe@fsij.org>
gpg>
Here, I enter ``addkey`` command. Then, I enter the passphrase of **key on PC**, I specified above. ::
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 28C0CD7C, created 2011-05-24
<PASSWORD-KEY-ON-PC>
gpg: gpg-agent is not available in this session
GnuPG askes kind of key. I select ``RSA (set your own capabilities)``. ::
Please select what kind of key you want:
(3) DSA (sign only)
(4) RSA (sign only)
(5) Elgamal (encrypt only)
(6) RSA (encrypt only)
(7) DSA (set your own capabilities)
(8) RSA (set your own capabilities)
Your selection? 8
And select ``Authenticate`` for the capabilities for this key. Initially, it's ``Sign`` and ``Encrypt``. I need to deselect ``Sign`` and ``Encryp``, and select ``Authenticate``. To do that, I enter ``s``, ``a``, and ``e``. ::
Possible actions for a RSA key: Sign Encrypt Authenticate
Current allowed actions: Sign Encrypt
(S) Toggle the sign capability
(E) Toggle the encrypt capability
(A) Toggle the authenticate capability
(Q) Finished
Your selection? s
Possible actions for a RSA key: Sign Encrypt Authenticate
Current allowed actions: Encrypt
(S) Toggle the sign capability
(E) Toggle the encrypt capability
(A) Toggle the authenticate capability
(Q) Finished
Your selection? a
Possible actions for a RSA key: Sign Encrypt Authenticate
Current allowed actions: Encrypt Authenticate
(S) Toggle the sign capability
(E) Toggle the encrypt capability
(A) Toggle the authenticate capability
(Q) Finished
Your selection? e
Possible actions for a RSA key: Sign Encrypt Authenticate
Current allowed actions: Authenticate
(S) Toggle the sign capability
(E) Toggle the encrypt capability
(A) Toggle the authenticate capability
(Q) Finished
OK, I set the capability of ``Authenticate``. I enter ``q`` to finish setting capabilities. ::
Your selection? q
GnuPG asks bitsize and expiration, I enter 2048 for bitsize and no expiration. Then, I confirm that I really create the key. ::
RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (2048)
Requested keysize is 2048 bits
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
Is this correct? (y/N) y
Really create? (y/N) y
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/28C0CD7C created: 2011-05-24 expires: never usage: SC
trust: ultimate validity: ultimate
sub 2048R/F01E19B7 created: 2011-05-24 expires: never usage: E
sub 2048R/B8929606 created: 2011-05-24 expires: never usage: A
[ultimate] (1). Niibe Yutaka <gniibe@fsij.org>
gpg>
I save the key. ::
gpg> save
$
Now, we have three keys (one primary key for signature and certification, subkey for encryption, and another subkey for authentication).
Publishing public key
=====================
I make a file for my public key by ``--export`` option of GnuPG. ::
$ gpg --armor --output gniibe.asc --export 4CA7BABE
and put it at: http://www.gniibe.org/gniibe.asc

177
doc/gnuk-keytocard-noremoval.rst Normal file
View File

@@ -0,0 +1,177 @@
=============================================
Key import from PC to Gnuk Token (no removal)
=============================================
This document describes how I put my **keys on PC** to the Token without removing keys from PC.
The difference is just not-to-save changes after key imports.
.. BREAK
After personalization, I put my keys into the Token.
Here is the log.
I invoke GnuPG with my key (4ca7babe) and with ``--homedir`` option to specify the directory which contains my secret keys. ::
$ gpg --homedir=/home/gniibe/tmp/gnuk-testing-dir --edit-key 4ca7babe
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.
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>
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,
and type ``1`` to say it's signature key. ::
gpg> keytocard
Really move the primary key? (y/N) y
gpg: detected reader `FSIJ Gnuk (0.12-38FF6A06) 00 00'
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, although they can be same.
I enter these passwords. ::
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 the Admin PIN
Enter Admin PIN: <PASSWORD-GNUK>
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.
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>
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
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>
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>
Thirdly, I select sub key of suthentication 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>
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
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>
The sub key is now on the Token and GnuPG says its card-no for it.
Lastly, I quit GnuPG. Note that I **don't** save changes. ::
gpg> quit
Save changes? (y/N) n
Quit without saving? (y/N) y
$
All keys are imported to Gnuk Token now.

183
doc/gnuk-keytocard.rst Normal file
View File

@@ -0,0 +1,183 @@
================================
Key import from PC to Gnuk Token
================================
This document describes how I put my **keys on PC** to the Token, and remove keys from PC.
Note that there is **no ways** to export keys from the Token, so please be careful.
.. BREAK
If you want to import same keys to multiple Tokens, please copy ``.gnupg`` directory before. In my case, I do something like following: ::
$ cp -a .gnupg tmp/gnuk-testing-dir
See `another document`_ to import keys to the Token from copied directory.
.. _another document: gnuk-keytocard-noremoval
After personalization, I put my keys into the Token.
Here is the log.
I invoke GnuPG with my key (4ca7babe). ::
$ gpg --edit-key 4ca7babe
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.
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>
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,
and type ``1`` to say it's signature key. ::
gpg> keytocard
Really move the primary key? (y/N) y
gpg: detected reader `FSIJ Gnuk (0.12-38FF6A06) 00 00'
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, although they can be same.
I enter these passwords. ::
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 the Admin PIN
Enter Admin PIN: <PASSWORD-GNUK>
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.
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>
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
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>
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>
Thirdly, I select sub key of suthentication 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>
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
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>
The sub key is now on the Token and GnuPG says its card-no for it.
Lastly, I save changes of **keys on PC** and quit GnuPG. ::
gpg> save
$
All secret keys are imported to Gnuk Token now. On PC, only references (card-no) to the Token remain.

118
doc/gnuk-personalization.rst Normal file
View File

@@ -0,0 +1,118 @@
=============================
Personalization of Gnuk Token
=============================
Personalize your Gnuk Token
===========================
Invoke GnuPG with the option ``--card-edit``. ::
$ gpg --card-edit
gpg: detected reader `FSIJ Gnuk (0.12-34006E06) 00 00'
Application ID ...: D276000124010200F517000000010000
Version ..........: 2.0
Manufacturer .....: FSIJ
Serial number ....: 00000001
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
Max. PIN lengths .: 127 127 127
PIN retry counter : 3 3 3
Signature counter : 0
Signature key ....: [none]
Encryption key....: [none]
Authentication key: [none]
General key info..: [none]
It shows the status of the card (as same as the output of ``gpg --card-status``). It shows token's name and its USB serial string (0.12-34006E06) from PC/SC-lite.
Then, GnuPG enters its own command interaction mode. The prompt is ``gpg/card>``.
Firstly, I change PIN of card user from factory setting (of "123456"). Note that, only changing PIN of user enables "admin less mode" of Gnuk. Admin password will become same one of user's. ::
gpg/card> passwd
gpg: OpenPGP card no. D276000124010200F517000000010000 detected
Please enter the PIN
Enter PIN: 123456
New PIN
Enter New PIN: <PASSWORD-OF-GNUK>
New PIN
Repeat this PIN: <PASSWORD-OF-GNUK>
PIN changed.
Secondly, enabling admin command, I put name of mine. Note that I input user's PIN (which I set above) here, because it is "admin less mode". ::
gpg/card> admin
Admin commands are allowed
gpg/card> name
Cardholder's surname: Niibe
Cardholder's given name: Yutaka
gpg: 3 Admin PIN attempts remaining before card is permanently locked
Please enter the Admin PIN
Enter Admin PIN: <PASSWORD-OF-GNUK>
Thirdly, I put some other informations, such as language, sex, login, and URL. URL specifies the place where I put my public keys. ::
gpg/card> lang
Language preferences: ja
gpg/card> sex
Sex ((M)ale, (F)emale or space): m
gpg/card> url
URL to retrieve public key: http://www.gniibe.org/gniibe.asc
gpg/card> login
Login data (account name): gniibe
Since I don't force PIN input everytime, toggle it to non-force-pin-for-signature. ::
gpg/card> forcesig
Lastly, I setup reset code. This is optional. ::
gpg/card> passwd
gpg: OpenPGP card no. D276000124010200F517000000010000 detected
1 - change PIN
2 - unblock PIN
3 - change Admin PIN
4 - set the Reset Code
Q - quit
Your selection? 4
gpg: 3 Admin PIN attempts remaining before card is permanently locked
Please enter the Admin PIN
Enter Admin PIN: <PASSWORD-OF-GNUK>
New Reset Code
Enter New PIN: <RESETCODE-OF-GNUK>
New Reset Code
Repeat this PIN: <RESETCODE-OF-GNUK>
Reset Code set.
1 - change PIN
2 - unblock PIN
3 - change Admin PIN
4 - set the Reset Code
Q - quit
Your selection? q
Then, I quit. ::
gpg/card> quit
That's all.

34
doc/gnuk-token-initial-configuration.rst Normal file
View File

@@ -0,0 +1,34 @@
===================================
Initial Configuration of Gnuk Token
===================================
Conditions
==========
I assume you are using GNU/Linux.
Preparation
===========
We need to kill ``scdaemon`` before configuring Gnuk Token. ::
$ gpg-connect-agent "SCD KILLSCD" "SCD BYE" /bye
Serial Number (optional)
========================
In the file ``GNUK_SERIAL_NUMBER``, each line has email and 6-byte serial number.
The tool ``../tool/gnuk_put_binary.py`` examines environment variable of ``EMAIL``, and writes serial number to Gnuk Token. ::
$ ../tool/gnuk_put_binary.py -s ../GNUK_SERIAL_NUMBER
Writing serial number
Token: FSIJ Gnuk (0.12-38FF6A06) 00 00
ATR: 3B DA 11 FF 81 B1 FE 55 1F 03 00 31 84 73 80 01 40 00 90 00 24
The tool ``../tool/gnuk_put_binary.py`` is for PC/SC Lite. Use
``../tool/gnuk_put_binary_libusb.py`` instead, if you don't use
PC/SC Lite but use libusb directly.

BIN
doc/images/gnuk-sticker.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 21 KiB

8
doc/index.rst
View File

@@ -13,6 +13,14 @@ Contents:
intro.rst intro.rst
development.rst development.rst
stop-scdaemon.rst
udev-rules.rst
generating-2048-RSA-key.rst
gnuk-token-initial-configuration.rst
gnuk-personalization.rst
gnuk-keytocard.rst
gnuk-keytocard-noremoval.rst
using-gnuk-token-with-another-computer.rst
Indices and tables Indices and tables

37
doc/stop-scdaemon.rst Normal file
View File

@@ -0,0 +1,37 @@
===========================
Stopping/Resetting SCDAEMON
===========================
There is a daemon named ``scdaemon`` behind gpg-agent, which handles
communication to smartcard/token.
Ideally, we don't need to care about ``scdaemon``, and it should
everything automatically. But, there are some cases (because of
bugs), where we need to talk to the daemon directly, in practice.
How to communicate SCDAEMON
===========================
We have a utility to communicate with a running gpg-agent, that's
gpg-connect-agent. We can use it to communicate with scdaemon,
as it supports sub-command "SCD", exactly for this purpose.
Stopping SCDAEMON
=================
To stop SCDAEMON and let it exit, type::
$ gpg-connect-agent "SCD KILLSCD" "SCD BYE" /bye
Then, you can confirm that there is no SCDAEMON any more by ``ps``
command.
Let GPG-AGENT/SCDAEMON learn
============================
To let gpg-agent/scdaemon learn, type::
$ gpg-connect-agent learn /bye

48
doc/udev-rules.rst Normal file
View File

@@ -0,0 +1,48 @@
===============================================
Device Configuration for Gnuk Token with libusb
===============================================
In order to use Gnuk Token with libusb, configuration of device is
needed for permissions. Note that this is not needed for the case of
PC/SC Lite, as it has its own device configuration.
Patching 60-gnupg.rules
=======================
In case of Debian, there is a file /lib/udev/rules.d/60-gnupg.rules.
This would be the place we need to change::
--- /lib/udev/rules.d/60-gnupg.rules.orig 2012-06-24 21:51:26.000000000 +0900
+++ /lib/udev/rules.d/60-gnupg.rules 2012-07-13 17:18:55.149587687 +0900
@@ -10,4 +10,7 @@
ATTR{idVendor}=="04e6", ATTR{idProduct}=="5115", ENV{ID_SMARTCARD_READER}="1", ENV{ID_SMARTCARD_READER_DRIVER}="gnupg"
ATTR{idVendor}=="20a0", ATTR{idProduct}=="4107", ENV{ID_SMARTCARD_READER}="1", ENV{ID_SMARTCARD_READER_DRIVER}="gnupg"
+# Gnuk
+ATTR{idVendor}=="234b", ATTR{idProduct}=="0000", ENV{ID_SMARTCARD_READER}="1", ENV{ID_SMARTCARD_READER_DRIVER}="gnupg"
+
LABEL="gnupg_rules_end"
Have a another configuration for reGNUal
========================================
For reGNUal (upgrade feature of Gnuk),
I also have a file /etc/udev/rules.d/92-gnuk.rules::
# For updating firmware, permission settings are needed.
SUBSYSTEMS=="usb", ATTRS{idVendor}=="234b", ATTRS{idProduct}=="0000", \
ENV{ID_USB_INTERFACES}=="*:ff0000:*", GROUP="pcscd"
Configuration for ST-Link/V2
============================
This is for development, but I also have a file
/etc/udev/rules.d/10-stlink.rules::
ACTION=="add", SUBSYSTEM=="usb", ATTR{idVendor}=="0483", ATTR{idProduct}=="3748", GROUP="tape", MODE="664", SYMLINK+="stlink"

173
doc/using-gnuk-token-with-another-computer.rst Normal file
View File

@@ -0,0 +1,173 @@
======================================
Using Gnuk Token with another computer
======================================
This document describes how you can use Gnuk Token on another PC (which is not the one you generate your keys).
Note that the Token only brings your secret keys, while ``.gnupg`` directory contains keyrings and trustdb, too.
.. BREAK
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``.
To do that, invoke GnuPG with ``--card-edit`` option. ::
$ gpg --card-edit
gpg: detected reader `FSIJ Gnuk (0.12-37006A06) 00 00'
Application ID ...: D276000124010200F517000000010000
Version ..........: 2.0
Manufacturer .....: FSIJ
Serial number ....: 00000001
Name of cardholder: Yutaka Niibe
Language prefs ...: ja
Sex ..............: male
URL of public key : http://www.gniibe.org/gniibe.asc
Login data .......: gniibe
Signature PIN ....: not forced
Key attributes ...: 2048R 2048R 2048R
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..: [none]
gpg/card>
It says, there is no key info related to this token on your PC (``[none]``).
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: Total number processed: 1
gpg: imported: 1 (RSA: 1)
gpg/card>
Good. The public key is now in ``.gnupg``. We can examine by ``gpg --list-keys``.
However, the secret key reference (to the token) is not in ``.gnupg`` yet.
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
Version ..........: 2.0
Manufacturer .....: FSIJ
Serial number ....: 00000001
Name of cardholder: Yutaka Niibe
Language prefs ...: ja
Sex ..............: male
URL of public key : http://www.gniibe.org/gniibe.asc
Login data .......: gniibe
Signature PIN ....: not forced
Key attributes ...: 2048R 2048R 2048R
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
gpg/card>
OK, now I can use the Token on this computer.
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.
To do that I do: ::
$ gpg --edit-key 4ca7babe
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.
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
[ 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. ::
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
[ unknown] (1). NIIBE Yutaka <gniibe@fsij.org>
[ unknown] (2) NIIBE Yutaka <gniibe@debian.org>
Please decide how far you trust this user to correctly verify other users' keys
(by looking at passports, checking fingerprints from different sources, etc.)
1 = I don't know or won't say
2 = I do NOT trust
3 = I trust marginally
4 = I trust fully
5 = I trust ultimately
m = back to the main menu
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
[ 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.
$
Next time 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.
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>
[ultimate] (2) NIIBE Yutaka <gniibe@debian.org>
gpg> quit
$