diff --git a/ChangeLog b/ChangeLog index c9200e4..f09502b 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +2016-06-21 Niibe Yutaka + + * doc/index.rst: Update documentation by an example + Ed25519/cv25519. + 2016-06-17 Niibe Yutaka * chopstx: Update to 1.0. diff --git a/doc/development.rst b/doc/development.rst index 9b03f9c..0e9f994 100644 --- a/doc/development.rst +++ b/doc/development.rst @@ -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 diff --git a/doc/generating-2048-RSA-key.rst b/doc/generating-2048-RSA-key.rst index 46d3b99..14b2e1a 100644 --- a/doc/generating-2048-RSA-key.rst +++ b/doc/generating-2048-RSA-key.rst @@ -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 - = key expires in n days - w = key expires in n weeks - m = key expires in n months - 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) " - - Real name: Niibe Yutaka - Email address: gniibe@fsij.org - Comment: - You selected this USER-ID: + $ gpg --quick-gen-key "Niibe Yutaka " + About to create a key for: "Niibe Yutaka " - - 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. - +(once for passphrase input, and another for confirmation), +. 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 - 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 + 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 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 . :: gpg> addkey - Key is protected. - You need a passphrase to unlock the secret key for - user: "Niibe Yutaka " - 2048-bit RSA key, ID 4CA7BABE, created 2010-10-15 - - 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 . + 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 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 $ diff --git a/doc/gnome3-gpg-settings.rst b/doc/gnome3-gpg-settings.rst deleted file mode 100644 index 5bb6126..0000000 --- a/doc/gnome3-gpg-settings.rst +++ /dev/null @@ -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. diff --git a/doc/gnuk-keytocard-noremoval.rst b/doc/gnuk-keytocard-noremoval.rst index 65704e7..4919e70 100644 --- a/doc/gnuk-keytocard-noremoval.rst +++ b/doc/gnuk-keytocard-noremoval.rst @@ -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. diff --git a/doc/gnuk-keytocard.rst b/doc/gnuk-keytocard.rst index aff8feb..13ebb30 100644 --- a/doc/gnuk-keytocard.rst +++ b/doc/gnuk-keytocard.rst @@ -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 + + 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 + [ultimate] (2) NIIBE Yutaka + + 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 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 " - 2048-bit RSA key, ID 4CA7BABE, created 2010-10-15 - - 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 + 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 - -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 + [ultimate] (2) NIIBE Yutaka 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 + 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 + [ultimate] (2) NIIBE Yutaka 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 " - 2048-bit RSA key, ID 084239CF, created 2010-10-15 - - gpg: writing new key + Please enter your passphrase, so that the secret key can be unlocked for this session + - 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 + 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 + [ultimate] (2) NIIBE Yutaka + +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 + 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 + [ultimate] (2) NIIBE Yutaka 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 + 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 + [ultimate] (2) NIIBE Yutaka 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 " - 2048-bit RSA key, ID 5BB065DC, created 2010-10-22 - - gpg: writing new key + Please enter your passphrase, so that the secret key can be unlocked for this session + - 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 + 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 + [ultimate] (2) NIIBE Yutaka -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. :: diff --git a/doc/gnuk-passphrase-setting.rst b/doc/gnuk-passphrase-setting.rst index 278d16d..66027e1 100644 --- a/doc/gnuk-passphrase-setting.rst +++ b/doc/gnuk-passphrase-setting.rst @@ -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 - 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 + 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. diff --git a/doc/gnuk-personalization.rst b/doc/gnuk-personalization.rst index 73d5512..43117db 100644 --- a/doc/gnuk-personalization.rst +++ b/doc/gnuk-personalization.rst @@ -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. diff --git a/doc/gnuk-token-initial-configuration.rst b/doc/gnuk-token-initial-configuration.rst index 54fe47f..3a690eb 100644 --- a/doc/gnuk-token-initial-configuration.rst +++ b/doc/gnuk-token-initial-configuration.rst @@ -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 diff --git a/doc/gpg-settings.rst b/doc/gpg-settings.rst index 57ab153..aa1f78d 100644 --- a/doc/gpg-settings.rst +++ b/doc/gpg-settings.rst @@ -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 ========== diff --git a/doc/index.rst b/doc/index.rst index c872bac..8c25709 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -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 diff --git a/doc/intro.rst b/doc/intro.rst index 0bae5c8..e9d8235 100644 --- a/doc/intro.rst +++ b/doc/intro.rst @@ -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 diff --git a/doc/stop-scdaemon.rst b/doc/stop-scdaemon.rst index 0c26a85..fdd52a0 100644 --- a/doc/stop-scdaemon.rst +++ b/doc/stop-scdaemon.rst @@ -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 diff --git a/doc/udev-rules.rst b/doc/udev-rules.rst index fae4873..53541bd 100644 --- a/doc/udev-rules.rst +++ b/doc/udev-rules.rst @@ -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:: diff --git a/doc/using-gnuk-token-with-another-computer.rst b/doc/using-gnuk-token-with-another-computer.rst index d33eaa4..6a4a4b6 100644 --- a/doc/using-gnuk-token-with-another-computer.rst +++ b/doc/using-gnuk-token-with-another-computer.rst @@ -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 " imported - gpg: no ultimately trusted keys found + gpg: requesting key E267B052364F028D from http server www.gniibe.org + gpg: key E267B052364F028D: public key "NIIBE Yutaka " 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 - 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 + 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 [ unknown] (2) NIIBE Yutaka - - 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 [ unknown] (2) NIIBE Yutaka @@ -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 [ unknown] (2) NIIBE Yutaka 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 [ultimate] (2) NIIBE Yutaka - + gpg> quit - $ + $ + +OK, all set. I'm ready to use my Gnuk Token on this PC.