Update document
authorNIIBE Yutaka <gniibe@fsij.org>
Fri, 8 Jul 2016 03:55:09 +0000 (12:55 +0900)
committerNIIBE Yutaka <gniibe@fsij.org>
Mon, 11 Jul 2016 03:55:09 +0000 (12:55 +0900)
doc/generating-key.rst
doc/index.rst
doc/intro.rst

index 14b2e1a..ede0b6e 100644 (file)
@@ -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 <YOUR-SECRET>.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
+          <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) 
+    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 <chuji@gniibe.org>"
+
+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 <chuji@gniibe.org>
+    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 <chuji@gniibe.org>
+
+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
+          <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) 
+    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 <chuji@gniibe.org>
+
+We type ``save`` to exit form gpg. ::
+
+    gpg> save
+    $ 
+  
index 8c25709..df82038 100644 (file)
@@ -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
index e9d8235..21b19e5 100644 (file)
@@ -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