From 5edcf32bb760669f5f47a5aefef95788e9f98e4d Mon Sep 17 00:00:00 2001 From: NIIBE Yutaka Date: Fri, 8 Jul 2016 12:55:09 +0900 Subject: [PATCH] Update document --- doc/generating-key.rst | 244 +++++++++++++++++++++++++++++++++++++++-- doc/index.rst | 2 +- doc/intro.rst | 6 +- 3 files changed, 242 insertions(+), 10 deletions(-) diff --git a/doc/generating-key.rst b/doc/generating-key.rst index 14b2e1a..ede0b6e 100644 --- a/doc/generating-key.rst +++ b/doc/generating-key.rst @@ -1,9 +1,11 @@ -============================ -Generating 2048-bit RSA keys -============================ +==================== +Generating key pairs +==================== In this section, we describe how to generate 2048-bit RSA keys. +You would like to use newer ECC keys instead of RSA keys. It is also described. + Key length of RSA ================= @@ -18,8 +20,7 @@ advises that 2048-bit keys should be viable until 2030. 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". +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. Further, @@ -37,9 +38,11 @@ considering device computation power and host software constraints. Thus, the key size is 2048-bit in the examples below. +When/If your environment allows use of newer ECC keys, newer ECC keys are recommended. -Generating keys on host PC -========================== + +Generating RSA keys on host PC +============================== Here is the example session to generate main key and a subkey for encryption. @@ -255,3 +258,230 @@ From the backup, we can recover privet key by invoking GnuPG with ``--import`` option. :: $ gpg --import .asc + + +Generating ECC keys on host PC +============================== + +Here is an example session log to create newer ECC keys. You need +libgcrypt 1.7 or newer and GnuPG 2.1.8 or newer. + +Next, we invoke gpg frontend with ``--expert`` and ``--full-gen-key`` option. :: + + $ gpg --expert --full-gen-key + 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. + +Then, we input ``9`` to select ECC primary key and ECC encryption subkey. :: + + 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) + (7) DSA (set your own capabilities) + (8) RSA (set your own capabilities) + (9) ECC and ECC + (10) ECC (sign only) + (11) ECC (set your own capabilities) + Your selection? 9 + +Next is the important selection. We input ``1`` to select "Curve25519". :: + + Please select which elliptic curve you want: + (1) Curve 25519 + (2) NIST P-256 + (3) NIST P-384 + (4) NIST P-521 + (5) Brainpool P-256 + (6) Brainpool P-384 + (7) Brainpool P-512 + (8) secp256k1 + Your selection? 1 + +You may see WARNING (it depends on version of GnuPG) and may been asked. Since it is what you want, please answer with 'y'. :: + + gpg: WARNING: Curve25519 is not yet part of the OpenPGP standard. + Use this curve anyway? (y/N) y + +It asks about expiration of 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) + Key does not expire at all + Is this correct? (y/N) y + +Then, it asks about a user ID. :: + + GnuPG needs to construct a user ID to identify your key. + + Real name: Kunisada Chuji + Email address: chuji@gniibe.org + Comment: + You selected this USER-ID: + "Kunisada Chuji " + +Lastly, it asks confirmation. :: + + Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o + +Then, it goes like this. :: + + 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. + +It asks the passphrase for keys by pop-up window, and then, finishes. :: + + gpg: key 17174C1A7C406DB5 marked as ultimately trusted + gpg: revocation certificate stored as '/home/gniibe.gnupg/openpgp-revocs.d/1719874a4fe5a1d8c465277d5a1bb27e3000f4ff.rev' + 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: 6 signed: 67 trust: 0-, 0q, 0n, 0m, 0f, 6u + gpg: depth: 1 valid: 67 signed: 40 trust: 67-, 0q, 0n, 0m, 0f, 0u + gpg: next trustdb check due at 2016-10-05 + pub ed25519 2016-07-08 + F478770235B60A230BE78005006A236C292C31D7 + uid [ultimate] Kunisada Chuji + sub cv25519 2016-07-08 + + $ + +We have the primary key with ed25519, and encryption subkey with cv25519. + + +Next, we add authentication subkey which can be used with OpenSSH. +We invoke gpg frontend with ``--edit-key`` and the key ID. :: + + $ gpg2 --expert --edit-key 17174C1A7C406DB5 + 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. + + sec ed25519/17174C1A7C406DB5 + created: 2016-07-08 expires: never usage: SC + trust: ultimate validity: ultimate + ssb cv25519/37A03183DF7B31B1 + created: 2016-07-08 expires: never usage: E + [ultimate] (1). Kunisada Chuji + +We invoke ``addkey`` subcommand. :: + + gpg> addkey + +It asks a kind of key, we input ``11`` to select ECC for authentication. :: + + 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) + (10) ECC (sign only) + (11) ECC (set your own capabilities) + (12) ECC (encrypt only) + (13) Existing key + Your selection? 11 + +and then, we specify "Authenticate" capability. :: + + Possible actions for a ECDSA/EdDSA key: Sign Authenticate + Current allowed actions: Sign + + (S) Toggle the sign capability + (A) Toggle the authenticate capability + (Q) Finished + + Your selection? a + + Possible actions for a ECDSA/EdDSA key: Sign Authenticate + Current allowed actions: Sign Authenticate + + (S) Toggle the sign capability + (A) Toggle the authenticate capability + (Q) Finished + + Your selection? s + + Possible actions for a ECDSA/EdDSA key: Sign Authenticate + Current allowed actions: Authenticate + + (S) Toggle the sign capability + (A) Toggle the authenticate capability + (Q) Finished + + Your selection? q + +Then, it asks which curve. We input ``1`` for "Curve25519". :: + + Please select which elliptic curve you want: + (1) Curve 25519 + (2) NIST P-256 + (3) NIST P-384 + (4) NIST P-521 + (5) Brainpool P-256 + (6) Brainpool P-384 + (7) Brainpool P-512 + (8) secp256k1 + Your selection? 1 + +It may ask confirmation with WARNING (depends on version). We say ``y``. :: + + gpg: WARNING: Curve25519 is not yet part of the OpenPGP standard. + Use this curve anyway? (y/N) y + +It asks 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) + Key does not expire at all + Is this correct? (y/N) y + +And the confirmation. :: + + Really create? (y/N) y + +It goes. :: + + 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. + +It asks the passphrase. And done. :: + + sec ed25519/17174C1A7C406DB5 + created: 2016-09-08 expires: never usage: SC + trust: ultimate validity: ultimate + ssb cv25519/37A03183DF7B31B1 + created: 2016-09-08 expires: never usage: E + ssb ed25519/4AD7D2428679DF5F + created: 2016-09-08 expires: never usage: A + [ultimate] (1). Kunisada Chuji + +We type ``save`` to exit form gpg. :: + + gpg> save + $ + diff --git a/doc/index.rst b/doc/index.rst index 8c25709..df82038 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -20,7 +20,7 @@ Contents: udev-rules.rst gnuk-token-initial-configuration.rst gnuk-personalization.rst - generating-2048-RSA-key.rst + generating-key.rst gnuk-keytocard.rst gnuk-keytocard-noremoval.rst gnuk-passphrase-setting.rst diff --git a/doc/intro.rst b/doc/intro.rst index e9d8235..21b19e5 100644 --- a/doc/intro.rst +++ b/doc/intro.rst @@ -9,6 +9,8 @@ Gnuk is an implementation of USB cryptographic token for GNU Privacy Guard. Gnuk supports OpenPGP card protocol version 2, and it runs on STM32F103 processor. +This document explains about Gnuk 1.2, which comes with ECC algorithm. + Cryptographic token and feature of Gnuk --------------------------------------- @@ -51,7 +53,7 @@ Host prerequisites for using Gnuk Token * [Optional] SSH: openssh -* [optional] Web: scute, firefox +* [experimental] Web: scute, firefox Usages @@ -60,4 +62,4 @@ Usages * Sign with GnuPG * Decrypt with GnuPG * Use with OpenSSH through gpg-agent (as ssh-agent) -* Use with Firefox through Scute for X.509 client certificate authentication +* [experimental] Use with Firefox through Scute for X.509 client certificate authentication