coelner/gnuk
1
0
Fork 0
mirror of https://salsa.debian.org/gnuk-team/gnuk/gnuk.git synced 2024-09-20 02:40:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

update documentation

Browse Source
This commit is contained in:
NIIBE Yutaka 2013-02-13 14:23:24 +09:00
parent 5213d9ab82
commit 5f2a8b835c
9 changed files with 110 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
README
View File

@ -660,10 +660,10 @@ Firmware update
See doc/note/firmware-update.
Read-only Git Repository
========================
Git Repositories
================
You can browse at http://www.gniibe.org/gitweb?p=gnuk.git;a=summary
You can browse at: http://www.gniibe.org/gitweb?p=gnuk.git;a=summary
You can get it by:
@ -674,6 +674,8 @@ or
$ git clone http://www.gniibe.org/git/gnuk.git/
Copy is available at: http://gitorious.org/gnuk
Information on the Web
======================

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

@ -133,7 +133,10 @@ Then, GnuPG generate keys. It takes some time. ::
Done.
Then, we create authentication subkey. Authentication subkey is not that common, but very useful (for SSH authentication). As it is not that common, we need ``--expert`` option for GnuPG. ::
Then, we create authentication subkey.
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.
@ -176,7 +179,10 @@ GnuPG asks kind of key. We select ``RSA (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``, ``e``, and ``a``. ::
And select ``Authenticate`` for the capabilities for this key.
Initially, it's ``Sign`` and ``Encrypt``.
I need to deselect ``Sign`` and ``Encrypt``, and select ``Authenticate``.
To do that, I enter ``s``, ``e``, and ``a``. ::
Possible actions for a RSA key: Sign Encrypt Authenticate
Current allowed actions: Sign Encrypt
@ -260,7 +266,8 @@ We save the key (to the storage of the host PC. ::
gpg> save
$
Now, we have three keys (one primary key for signature and certification, subkey for encryption, and another subkey for authentication).
Now, we have three keys (one primary key for signature and certification,
subkey for encryption, and another subkey for authentication).
Publishing public key

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

@ -4,7 +4,8 @@ GnuPG settings for GNOME 3
In the article `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.
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
@ -12,19 +13,26 @@ It was for GNOME 2. The old days was good, we just disabled GNOME-keyrings inte
GNOME keyrings in GNOME 3
=========================
It seems that it is more integrated into the desktop. It is difficult to kill it. It would be possible to kill it simply, but then, I can't use, say, wi-fi access (which needs to access "secrets") any more.
It seems that it is more integrated into the desktop.
It is difficult to kill it. It would be possible to kill it simply,
but then, I can't use, say, wi-fi access (which needs to access "secrets")
any more.
We can't use GNOME configuration tool to disable interference by GNOME keyrings any more. It seems that desktop should not have customization these days.
We can't use GNOME configuration tool to disable interference by
GNOME keyrings any more. It seems that desktop should not have
customization these days.
GNOME-SESSION-PROPERTIES
========================
After struggling some ours, I figured out it is GNOME-SESSION-PROPERTIES to disable the interference. Invoking::
After struggling some hours, I figured out 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".
and at the tab of "Startup Programs", I removed radio check buttons
for "GPG Password Agent" and "SSH Key Agent".
Now, I use gpg-agent for GnuPG Agent and SSH agent with Gnuk Token.

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

@ -2,17 +2,17 @@
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.
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. ::
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.
@ -54,7 +54,10 @@ and type ``1`` to say it's 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.
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. ::
@ -74,7 +77,8 @@ I enter these passwords. ::
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.
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'. ::
@ -87,7 +91,8 @@ Secondly, I import my subkey of encryption. I select key number '1'. ::
(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. ::
I type ``keytocard`` command to import this subkey to Gnuk Token.
I select ``2`` as it's encryption key. ::
gpg> keytocard
Signature key ....: [none]
@ -138,7 +143,8 @@ Thirdly, I select sub key of authentication which has key number '2'. ::
(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. ::
I type ``keytocard`` command to import this subkey to Gnuk Token.
I select ``3`` as it's authentication key. ::
gpg> keytocard
Signature key ....: [none]

26
doc/gnuk-keytocard.rst
View File

@ -2,13 +2,17 @@
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.
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.
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: ::
If you want to import same keys to multiple Tokens,
please copy ``.gnupg`` directory beforehand.
In my case, I do something like following: ::
$ cp -a .gnupg tmp/gnuk-testing-dir
@ -62,7 +66,10 @@ and type ``1`` to say it's 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.
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. ::
@ -95,7 +102,8 @@ Secondly, I import my subkey of encryption. I select key number '1'. ::
(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. ::
I type ``keytocard`` command to import this subkey to Gnuk Token.
I select ``2`` as it's encryption key. ::
gpg> keytocard
Signature key ....: [none]
@ -146,7 +154,8 @@ Thirdly, I select sub key of authentication which has key number '2'. ::
(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. ::
I type ``keytocard`` command to import this subkey to Gnuk Token.
I select ``3`` as it's authentication key. ::
gpg> keytocard
Signature key ....: [none]
@ -180,4 +189,5 @@ 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.
All secret keys are imported to Gnuk Token now.
On PC, only references (card-no) to the Token remain.

23
doc/gnuk-personalization.rst
View File

@ -48,7 +48,12 @@ Besides, some people sometimes prefer the word "passphrase" to
"password", as it can encourage to have longer string, but it means
same thing and it just refer user-password or admin-password.
Firstly, I change PIN of card user from factory setting (of "123456"). Note that, by only changing user's PIN, it enables "admin less mode" of Gnuk. "Admin less mode" means that admin password will become same one of user's. That is, PW1 = PW3. Note that *the length of PIN should be more than (or equals to) 8* for "admin less mode". ::
Firstly, I change PIN of card user from factory setting (of "123456").
Note that, by only changing user's PIN, it enables "admin less mode" of Gnuk.
"Admin less mode" means that admin password will become same one of user's.
That is, PW1 = PW3.
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
@ -68,9 +73,15 @@ OpenPGPcard specification. By using "admin less mode", it will be
only a sigle password for user to memorize, and it will be easier if a token
is used by an individual.
(If you want normal way ("admin full mode" in Gnuk's term), that is, user-password *and* admin-password independently, please change admin-password at first. Then, the token works as same as OpenPGPcard specification with regards to PW1 and PW3.)
(If you want normal way ("admin full mode" in Gnuk's term),
that is, user-password *and* admin-password independently,
please change admin-password at first.
Then, the token works as same as OpenPGPcard specification
with regards to PW1 and PW3.)
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". ::
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
@ -83,7 +94,8 @@ Secondly, enabling admin command, I put name of mine. Note that I input user's
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. ::
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
@ -97,7 +109,8 @@ Thirdly, I put some other informations, such as language, sex, login, and URL.
gpg/card> login
Login data (account name): gniibe
Since I don't force PIN input everytime, toggle it to non-force-pin-for-signature. ::
Since I don't force PIN input everytime,
toggle it to non-force-pin-for-signature. ::
gpg/card> forcesig

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

@ -2,6 +2,12 @@
Initial Configuration of Gnuk Token
===================================
This is optional. You don't need to setup the serial number of Gnuk Token,
as it comes with its default serial number based on MCU's chip ID.
You can setup the serial number of Gnuk Token only once.
Conditions
==========
@ -11,7 +17,7 @@ I assume you are using GNU/Linux.
Preparation
===========
We need to kill ``scdaemon`` before configuring Gnuk Token. ::
Make sure there is no ``scdaemon`` for configuring Gnuk Token. You can kill ``scdaemon`` by: ::
$ gpg-connect-agent "SCD KILLSCD" "SCD BYE" /bye
@ -19,16 +25,19 @@ We need to kill ``scdaemon`` before configuring Gnuk Token. ::
Serial Number (optional)
========================
In the file ``GNUK_SERIAL_NUMBER``, each line has email and 6-byte serial number.
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.py`` examines environment variable of ``EMAIL``, and writes serial number to Gnuk Token. ::
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.py -s ../GNUK_SERIAL_NUMBER
$ ../tool/gnuk_put_binary_libusb.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
Device: 006
Configuration: 1
Interface: 0
d2 76 00 01 24 01 02 00 f5 17 00 00 00 01 00 00
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.
The example above is the case of libusb version.
Use the tool ``../tool/gnuk_put_binary.py`` instead , for PC/SC Lite.
You need PyScard for this.

4
doc/gpg-settings.rst
View File

@ -22,10 +22,12 @@ I create ``.gnupg/gpg.conf`` file with the following content. ::
Let gpg-agent manage SSH key
============================
I deactivate seahose-agent. Also, I deactivate gnome-keyring managing SSH key. ::
I deactivate seahose-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. ::
enable-ssh-support

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

@ -2,16 +2,18 @@
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).
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.
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``.
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. ::
@ -58,7 +60,9 @@ 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. ::
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>
@ -99,7 +103,8 @@ 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.
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: ::