update documentation
authorNIIBE Yutaka <gniibe@fsij.org>
Wed, 13 Feb 2013 05:23:24 +0000 (14:23 +0900)
committerNIIBE Yutaka <gniibe@fsij.org>
Wed, 13 Feb 2013 05:23:24 +0000 (14:23 +0900)
README
doc/generating-2048-RSA-key.rst
doc/gnome3-gpg-settings.rst
doc/gnuk-keytocard-noremoval.rst
doc/gnuk-keytocard.rst
doc/gnuk-personalization.rst
doc/gnuk-token-initial-configuration.rst
doc/gpg-settings.rst
doc/using-gnuk-token-with-another-computer.rst

diff --git a/README b/README
index 256ea99..018e2bf 100644 (file)
--- a/README
+++ b/README
@@ -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
 ======================
index 3164c54..d47f779 100644 (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
index f6bb312..2fcf210 100644 (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.
index f350376..358d2ea 100644 (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]
index 2c49292..792f6f6 100644 (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.
index 51d737c..cdadadf 100644 (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
 
index d2a5c9a..d3382c7 100644 (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 example above is the case of libusb version.
 
-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.
+Use the tool ``../tool/gnuk_put_binary.py`` instead , for PC/SC Lite.
+You need PyScard for this.
index d573995..07362f4 100644 (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
index 200fe77..188ec1a 100644 (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: ::