Fix typo
[gnuk/gnuk.git] / doc / generating-key.rst
1 ====================
2 Generating key pairs
3 ====================
4
5 In this section, we describe how to generate 2048-bit RSA keys.
6
7 You would like to use newer ECC keys instead of RSA keys.  It is also described.
8
9
10 Key length of RSA
11 =================
12
13 In 2005, NIST (National Institute of Standards and Technology, USA)
14 issued the first revision of NIST Special Publication 800-57, 
15 "Recommendation for Key Management".
16
17 In 800-57, NIST advises that 1024-bit RSA keys will no longer be
18 viable after 2010 and advises moving to 2048-bit RSA keys.  NIST
19 advises that 2048-bit keys should be viable until 2030.
20
21 As of 2016, GnuPG's default for generating RSA key is 2048-bit.
22
23 Some people have preference on RSA 4096-bit keys, considering "longer is better".
24
25 However, "longer is better" is not always true.  When it's long, it
26 requires more computational resource, memory, and storage.  Further,
27 it consumes more power for nomal usages.  These days, many people has
28 enough computational resource, that would be true, but less is better
29 for power consumption, isn't it?
30
31 For security, the key length is just a single factor.  We had and will have
32 algorithm issues, too.  It is true that it's difficult to update
33 our public keys, but this problem wouldn't be solved by just having
34 longer keys.
35
36 We deliberately recommend use of RSA 2048-bit keys for Gnuk,
37 considering device computation power and host software constraints.
38
39 Thus, the key size is 2048-bit in the examples below.
40
41 When/If your environment allows use of newer ECC keys, newer ECC keys are recommended.
42
43
44 Generating RSA keys on host PC
45 ==============================
46
47 Here is the example session to generate main key and a subkey for encryption.
48
49 I invoke GnuPG with ``--quick-gen-key`` option. ::
50
51   $ gpg --quick-gen-key "Niibe Yutaka <gniibe@fsij.org>"
52   About to create a key for:
53       "Niibe Yutaka <gniibe@fsij.org>"
54
55   Continue? (Y/n) y
56
57 It askes passphrase for this **key on host PC**.
58 Note that this is a passphrase for the key on host PC.
59 It is different thing to the passphrase of Gnuk Token.
60 We enter two same inputs two times
61 (once for passphrase input, and another for confirmation),
62 <PASSWORD-KEY-ON-PC>.
63
64 Then, GnuPG generate keys.  It takes some time.  ::
65   
66   We need to generate a lot of random bytes. It is a good idea to perform
67   some other action (type on the keyboard, move the mouse, utilize the
68   disks) during the prime generation; this gives the random number
69   generator a better chance to gain enough entropy.
70   gpg: key 76A9392B02CD15D1 marked as ultimately trusted
71   gpg: revocation certificate stored as '/home/gniibe.gnupg/openpgp-revocs.d/36CE0B8408CFE5CD07F94ACF76A9392B02CD15D1.rev'
72   public and secret key created and signed.
73
74   gpg: checking the trustdb
75   gpg: marginals needed: 3  completes needed: 1  trust model: pgp
76   gpg: depth: 0  valid:   1  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 1u
77   pub   rsa2048 2016-06-20 [S]
78         36CE0B8408CFE5CD07F94ACF76A9392B02CD15D1
79   uid           [ultimate] Niibe Yutaka <gniibe@fsij.org>
80   sub   rsa2048 2016-06-20 []
81
82 Done.
83
84 Then, we create authentication subkey.
85 Authentication subkey is not that common,
86 but very useful (for SSH authentication).
87 As it is not that common, we need ``--expert`` option for GnuPG. ::
88
89   gpg (GnuPG) 2.1.13; Copyright (C) 2016 Free Software Foundation, Inc.
90   This is free software: you are free to change and redistribute it.
91   There is NO WARRANTY, to the extent permitted by law.
92
93   Secret key is available.
94
95   sec  rsa2048/76A9392B02CD15D1
96        created: 2016-06-20  expires: never       usage: SC  
97        trust: ultimate      validity: ultimate
98   ssb  rsa2048/4BD1EB26F0E607E6
99        created: 2016-06-20  expires: never       usage: E   
100   [ultimate] (1). Niibe Yutaka <gniibe@fsij.org>
101   
102   gpg> 
103
104 Here, it displays that there are main key and a subkey.
105 It prompts sub-command with ``gpg>`` .
106
107 Here, we enter ``addkey`` sub-command.
108
109   gpg> addkey
110     
111 GnuPG asks kind of key.  We select ``RSA (set your own capabilities)``. ::
112
113   Please select what kind of key you want:
114      (3) DSA (sign only)
115      (4) RSA (sign only)
116      (5) Elgamal (encrypt only)
117      (6) RSA (encrypt only)
118      (7) DSA (set your own capabilities)
119      (8) RSA (set your own capabilities)
120     (10) ECC (sign only)
121     (11) ECC (set your own capabilities)
122     (12) ECC (encrypt only)
123     (13) Existing key
124   Your selection? 8
125
126 And select ``Authenticate`` for the capabilities for this key.
127 Initially, it's ``Sign`` and  ``Encrypt``.
128 I need to deselect ``Sign`` and ``Encrypt``, and select ``Authenticate``.
129 To do that, I enter ``s``, ``e``, and ``a``.  ::
130
131   Possible actions for a RSA key: Sign Encrypt Authenticate 
132   Current allowed actions: Sign Encrypt 
133   
134      (S) Toggle the sign capability
135      (E) Toggle the encrypt capability
136      (A) Toggle the authenticate capability
137      (Q) Finished
138   
139   Your selection? s
140   
141   Possible actions for a RSA key: Sign Encrypt Authenticate 
142   Current allowed actions: Encrypt 
143   
144      (S) Toggle the sign capability
145      (E) Toggle the encrypt capability
146      (A) Toggle the authenticate capability
147      (Q) Finished
148   
149   Your selection? e
150   
151   Possible actions for a RSA key: Sign Encrypt Authenticate 
152   Current allowed actions: 
153
154      (S) Toggle the sign capability
155      (E) Toggle the encrypt capability
156      (A) Toggle the authenticate capability
157      (Q) Finished
158   
159   Your selection? a
160   
161   Possible actions for a RSA key: Sign Encrypt Authenticate 
162   Current allowed actions: Authenticate 
163   
164      (S) Toggle the sign capability
165      (E) Toggle the encrypt capability
166      (A) Toggle the authenticate capability
167      (Q) Finished
168
169 OK, we set the capability of ``Authenticate``.
170 We enter ``q`` to finish setting capabilities. ::
171
172   Your selection? q
173
174 GnuPG asks bitsize and expiration, we enter 2048 for bitsize and no expiration.
175 Then, we confirm that we really create the key. ::
176
177   RSA keys may be between 1024 and 4096 bits long.
178   What keysize do you want? (2048) 
179   Requested keysize is 2048 bits
180   Please specify how long the key should be valid.
181            0 = key does not expire
182         <n>  = key expires in n days
183         <n>w = key expires in n weeks
184         <n>m = key expires in n months
185         <n>y = key expires in n years
186   Key is valid for? (0) 0
187   Key does not expire at all
188   Is this correct? (y/N) y
189   Really create? (y/N) y
190
191 Then, it askes the passphrase, it is the passphrase of **key on host PC**.
192 It's the one we entered above as <PASSWORD-KEY-ON-PC>.
193
194 Then, GnuPG generate the key. ::
195
196   We need to generate a lot of random bytes. It is a good idea to perform
197   some other action (type on the keyboard, move the mouse, utilize the
198   disks) during the prime generation; this gives the random number
199   generator a better chance to gain enough entropy.
200
201   sec  rsa2048/76A9392B02CD15D1
202        created: 2016-06-20  expires: never       usage: SC  
203        trust: ultimate      validity: ultimate
204   ssb  rsa2048/4BD1EB26F0E607E6
205        created: 2016-06-20  expires: never       usage: E   
206   ssb  rsa2048/F3BA52C64012198D
207        created: 2016-06-20  expires: never       usage: A   
208   [ultimate] (1). Niibe Yutaka <gniibe@fsij.org>
209
210   gpg> 
211
212 We save the key (to the storage of the host PC). ::
213
214   gpg> save
215   $ 
216
217 Now, we have three keys (one primary key for signature and certification,
218 subkey for encryption, and another subkey for authentication).
219
220
221 Publishing public key
222 =====================
223
224 We make a file for the public key by ``--export`` option of GnuPG. ::
225
226   $ gpg --armor --output <YOUR-KEY>.asc --export <YOUR-KEY-ID>
227
228 We can publish the file by web server.  Or we can publish the key
229 to a keyserver, by invoking GnuPG with ``--send-keys`` option.  ::
230
231   $ gpg --keyserver pool.sks-keyservers.net --send-keys <YOUR-KEY-ID>
232
233 Here, pool.sks-keyservers.net is a keyserver, which is widely used.
234
235
236 Backup the private key
237 ======================
238
239 There are some ways to back up private key, such that backup .gnupg
240 directory entirely, or use of paperkey, etc.
241 Here, we describe backup by ASCII file.
242 ASCII file is good, because it has less risk on transfer.
243 Binary file has a risk to be modified on transfer.
244
245 Note that the key on host PC is protected by passphrase (which
246 is <PASSWORD-KEY-ON-PC> in the example above).  Using the key
247 from the backup needs this passphrase.  It is common that
248 people will forget passphrase for backup.  Never forget it.
249 You have been warned.
250
251 To make ASCII backup for private key,
252 invokde GnuPG with ``--armor`` option and ``--export-secret-keys``
253 specifying the key identifier. ::
254
255   $ gpg --armor --output <YOUR-SECRET>.asc --export-secret-keys <YOUR-KEY-ID>
256
257 From the backup,
258 we can recover privet key by invoking GnuPG with ``--import`` option. ::
259
260   $ gpg --import <YOUR-SECRET>.asc
261
262
263 Generating ECC keys on host PC
264 ==============================
265
266 Here is an example session log to create newer ECC keys.  You need
267 libgcrypt 1.7 or newer and GnuPG 2.1.8 or newer.
268
269 Next, we invoke gpg frontend with ``--expert`` and ``--full-gen-key`` option. ::
270
271     $ gpg --expert --full-gen-key
272     gpg (GnuPG) 2.1.13; Copyright (C) 2016 Free Software Foundation, Inc.
273     This is free software: you are free to change and redistribute it.
274     There is NO WARRANTY, to the extent permitted by law.
275
276 Then, we input ``9`` to select ECC primary key and ECC encryption subkey. ::
277     
278     Please select what kind of key you want:
279        (1) RSA and RSA (default)
280        (2) DSA and Elgamal
281        (3) DSA (sign only)
282        (4) RSA (sign only)
283        (7) DSA (set your own capabilities)
284        (8) RSA (set your own capabilities)
285        (9) ECC and ECC
286       (10) ECC (sign only)
287       (11) ECC (set your own capabilities)
288     Your selection? 9
289
290 Next is the important selection.  We input ``1`` to select "Curve25519". ::
291
292     Please select which elliptic curve you want:
293        (1) Curve 25519
294        (2) NIST P-256
295        (3) NIST P-384
296        (4) NIST P-521
297        (5) Brainpool P-256
298        (6) Brainpool P-384
299        (7) Brainpool P-512
300        (8) secp256k1
301     Your selection? 1
302
303 You may see WARNING (it depends on version of GnuPG) and may been asked.  Since it is what you want, please answer with 'y'. ::
304
305     gpg: WARNING: Curve25519 is not yet part of the OpenPGP standard.
306     Use this curve anyway? (y/N) y
307
308 It asks about expiration of key. ::
309
310     Please specify how long the key should be valid.
311              0 = key does not expire
312           <n>  = key expires in n days
313           <n>w = key expires in n weeks
314           <n>m = key expires in n months
315           <n>y = key expires in n years
316     Key is valid for? (0) 
317     Key does not expire at all
318     Is this correct? (y/N) y
319
320 Then, it asks about a user ID. ::
321
322     GnuPG needs to construct a user ID to identify your key.
323     
324     Real name: Kunisada Chuji
325     Email address: chuji@gniibe.org
326     Comment: 
327     You selected this USER-ID:
328         "Kunisada Chuji <chuji@gniibe.org>"
329
330 Lastly, it asks confirmation. ::
331
332     Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o
333
334 Then, it goes like this. ::
335
336     We need to generate a lot of random bytes. It is a good idea to perform
337     some other action (type on the keyboard, move the mouse, utilize the
338     disks) during the prime generation; this gives the random number
339     generator a better chance to gain enough entropy.
340     We need to generate a lot of random bytes. It is a good idea to perform
341     some other action (type on the keyboard, move the mouse, utilize the
342     disks) during the prime generation; this gives the random number
343     generator a better chance to gain enough entropy.
344
345 It asks the passphrase for keys by pop-up window, and then, finishes. ::
346     
347     gpg: key 17174C1A7C406DB5 marked as ultimately trusted
348     gpg: revocation certificate stored as '/home/gniibe.gnupg/openpgp-revocs.d/1719874a4fe5a1d8c465277d5a1bb27e3000f4ff.rev'
349     public and secret key created and signed.
350     
351     gpg: checking the trustdb
352     gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
353     gpg: depth: 0  valid:   6  signed:  67  trust: 0-, 0q, 0n, 0m, 0f, 6u
354     gpg: depth: 1  valid:  67  signed:  40  trust: 67-, 0q, 0n, 0m, 0f, 0u
355     gpg: next trustdb check due at 2016-10-05
356     pub   ed25519 2016-07-08
357           F478770235B60A230BE78005006A236C292C31D7
358     uid         [ultimate] Kunisada Chuji <chuji@gniibe.org>
359     sub   cv25519 2016-07-08
360     
361     $
362
363 We have the primary key with ed25519, and encryption subkey with cv25519.
364
365
366 Next, we add authentication subkey which can be used with OpenSSH.
367 We invoke gpg frontend with ``--edit-key`` and the key ID. ::
368
369     $ gpg2 --expert --edit-key 17174C1A7C406DB5
370     gpg (GnuPG) 2.1.13; Copyright (C) 2016 Free Software Foundation, Inc.
371     This is free software: you are free to change and redistribute it.
372     There is NO WARRANTY, to the extent permitted by law.
373     
374     Secret key is available.
375     
376     sec  ed25519/17174C1A7C406DB5
377          created: 2016-07-08  expires: never       usage: SC  
378          trust: ultimate      validity: ultimate
379     ssb  cv25519/37A03183DF7B31B1
380          created: 2016-07-08  expires: never       usage: E   
381     [ultimate] (1). Kunisada Chuji <chuji@gniibe.org>
382
383 We invoke ``addkey`` subcommand. ::
384
385     gpg> addkey
386
387 It asks a kind of key, we input ``11`` to select ECC for authentication. ::
388
389     Please select what kind of key you want:
390        (3) DSA (sign only)
391        (4) RSA (sign only)
392        (5) Elgamal (encrypt only)
393        (6) RSA (encrypt only)
394        (7) DSA (set your own capabilities)
395        (8) RSA (set your own capabilities)
396       (10) ECC (sign only)
397       (11) ECC (set your own capabilities)
398       (12) ECC (encrypt only)
399       (13) Existing key
400     Your selection? 11
401
402 and then, we specify "Authenticate" capability. ::
403
404     Possible actions for a ECDSA/EdDSA key: Sign Authenticate 
405     Current allowed actions: Sign 
406     
407        (S) Toggle the sign capability
408        (A) Toggle the authenticate capability
409        (Q) Finished
410     
411     Your selection? a
412     
413     Possible actions for a ECDSA/EdDSA key: Sign Authenticate 
414     Current allowed actions: Sign Authenticate 
415     
416        (S) Toggle the sign capability
417        (A) Toggle the authenticate capability
418        (Q) Finished
419     
420     Your selection? s
421     
422     Possible actions for a ECDSA/EdDSA key: Sign Authenticate 
423     Current allowed actions: Authenticate 
424     
425        (S) Toggle the sign capability
426        (A) Toggle the authenticate capability
427        (Q) Finished
428     
429     Your selection? q
430
431 Then, it asks which curve.  We input ``1`` for "Curve25519". ::
432
433     Please select which elliptic curve you want:
434        (1) Curve 25519
435        (2) NIST P-256
436        (3) NIST P-384
437        (4) NIST P-521
438        (5) Brainpool P-256
439        (6) Brainpool P-384
440        (7) Brainpool P-512
441        (8) secp256k1
442     Your selection? 1
443
444 It may ask confirmation with WARNING (depends on version).  We say ``y``. ::
445
446     gpg: WARNING: Curve25519 is not yet part of the OpenPGP standard.
447     Use this curve anyway? (y/N) y
448
449 It asks expiration of the key. ::
450
451     Please specify how long the key should be valid.
452              0 = key does not expire
453           <n>  = key expires in n days
454           <n>w = key expires in n weeks
455           <n>m = key expires in n months
456           <n>y = key expires in n years
457     Key is valid for? (0) 
458     Key does not expire at all
459     Is this correct? (y/N) y
460
461 And the confirmation. ::
462
463     Really create? (y/N) y
464
465 It goes. ::
466
467     We need to generate a lot of random bytes. It is a good idea to perform
468     some other action (type on the keyboard, move the mouse, utilize the
469     disks) during the prime generation; this gives the random number
470     generator a better chance to gain enough entropy.
471
472 It asks the passphrase.  And done. ::
473     
474     sec  ed25519/17174C1A7C406DB5
475          created: 2016-09-08  expires: never       usage: SC  
476          trust: ultimate      validity: ultimate
477     ssb  cv25519/37A03183DF7B31B1
478          created: 2016-09-08  expires: never       usage: E   
479     ssb  ed25519/4AD7D2428679DF5F
480          created: 2016-09-08  expires: never       usage: A   
481     [ultimate] (1). Kunisada Chuji <chuji@gniibe.org>
482
483 We type ``save`` to exit form gpg. ::
484
485     gpg> save
486     $ 
487