keygen.txt

   1 ---
   2 ---
   3 Key Generation
   4 ==============
   5
   6 include::menu.inc[]
   7
   8 == Generate GPG signing key pair
   9
  10 The guide will explain how to generate a new key pair, how to create a
  11 signing sub key and how to strip the secret master key to avoid leaking
  12 your primary secret key identity in case your signing key (or the entire
  13 +~/.gnupg/+) ever gets lost.
  14
  15
  16 === 1) Generate new, fresh key pair on a secure machine
  17
  18 ----
  19 $ mkdir /tmp/signing
  20 $ chmod 0700 /tmp/signing
  21 $ gpg --homedir /tmp/signing --gen-key
  22 gpg (GnuPG) 1.4.18; Copyright (C) 2014 Free Software Foundation, Inc.
  23 This is free software: you are free to change and redistribute it.
  24 There is NO WARRANTY, to the extent permitted by law.
  25
  26 gpg: keyring `/tmp/signing/secring.gpg' created
  27 gpg: keyring `/tmp/signing/pubring.gpg' created
  28 ----
  29
  30 TIP: Pick 4 to generate an RSA-only key and choose a key size of 4096 bits.
  31      For this how-to I choose to set no expiry at all.
  32
  33 ----
  34 Please select what kind of key you want:
  35    (1) RSA and RSA (default)
  36    (2) DSA and Elgamal
  37    (3) DSA (sign only)
  38    (4) RSA (sign only)
  39 Your selection? 4
  40 RSA keys may be between 1024 and 4096 bits long.
  41 What keysize do you want? (2048) 4096
  42 Requested keysize is 4096 bits
  43 Please specify how long the key should be valid.
  44          0 = key does not expire
  45       <n>  = key expires in n days
  46       <n>w = key expires in n weeks
  47       <n>m = key expires in n months
  48       <n>y = key expires in n years
  49 Key is valid for? (0)
  50 Key does not expire at all
  51 Is this correct? (y/N) y
  52 ----
  53
  54 TIP: GPG will ask about your user identity now, provide your real name and
  55      the mail address you intend to use for your project communication.
  56      I also suggest to provide a meaningful comment, eg. "LEDE Signing Key"
  57
  58
  59 ----
  60 You need a user ID to identify your key; the software constructs the user ID
  61 from the Real Name, Comment and Email Address in this form:
  62     "Heinrich Heine (Der Dichter) <heinrichh@duesseldorf.de>"
  63
  64 Real name: Jo-Philipp Wich
  65 Email address: jo@mein.io
  66 Comment: LEDE Signing Key
  67 You selected this USER-ID:
  68     "Jo-Philipp Wich (LEDE Signing Key) <jo@mein.io>"
  69
  70 Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O
  71 You need a Passphrase to protect your secret key.
  72 ----
  73
  74 TIP: At this point enter a good pass phrase twice to protect your secret
  75      key, the command will take a while to gather entropy and complete key
  76      until it'll eventually print the key summary:
  77
  78 ----
  79 gpg: /tmp/signing/trustdb.gpg: trustdb created
  80 gpg: key 612A0E98 marked as ultimately trusted
  81 public and secret key created and signed.
  82
  83 gpg: checking the trustdb
  84 gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
  85 gpg: depth: 0  valid:   1  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 1u
  86 pub   4096R/612A0E98 2016-04-05
  87       Key fingerprint = 69B2 6A27 62D0 65E6 6F59  6755 C76F DE50 612A 0E98
  88 uid                  Jo-Philipp Wich (LEDE Signing Key) <jo@mein.io>
  89
  90 Note that this key cannot be used for encryption.  You may want to use
  91 the command "--edit-key" to generate a subkey for this purpose.
  92 ----
  93
  94 === 2) Generate a sub key
  95
  96 ----
  97 $ gpg --homedir /tmp/signing --edit-key jo@mein.io
  98 gpg (GnuPG) 1.4.18; Copyright (C) 2014 Free Software Foundation, Inc.
  99 This is free software: you are free to change and redistribute it.
 100 There is NO WARRANTY, to the extent permitted by law.
 101
 102 Secret key is available.
 103
 104 pub  4096R/612A0E98  created: 2016-04-05  expires: never       usage: SC
 105                      trust: ultimate      validity: ultimate
 106 [ultimate] (1). Jo-Philipp Wich (LEDE Signing Key) <jo@mein.io>
 107 ----
 108
 109 TIP: In the now appearing interactive gpg prompt enter "addkey" to create
 110      a new signing subkey. GnuPG will ask your to unlock the master key using
 111      the passphrase you've given in the previous step.
 112
 113 ----
 114 gpg> addkey
 115 Key is protected.
 116
 117 You need a passphrase to unlock the secret key for
 118 user: "Jo-Philipp Wich (LEDE Signing Key) <jo@mein.io>"
 119 4096-bit RSA key, ID 612A0E98, created 2016-04-05
 120
 121 Please select what kind of key you want:
 122    (3) DSA (sign only)
 123    (4) RSA (sign only)
 124    (5) Elgamal (encrypt only)
 125    (6) RSA (encrypt only)
 126 ----
 127
 128 TIP: We'll use a signing-only 4096bit RSA key with an validity of two years
 129
 130 ----
 131 Your selection? 4
 132 RSA keys may be between 1024 and 4096 bits long.
 133 What keysize do you want? (2048) 4096
 134 Requested keysize is 4096 bits
 135 Please specify how long the key should be valid.
 136          0 = key does not expire
 137       <n>  = key expires in n days
 138       <n>w = key expires in n weeks
 139       <n>m = key expires in n months
 140       <n>y = key expires in n years
 141 Key is valid for? (0) 730
 142 Key expires at Thu Apr  5 18:19:42 2018 CEST
 143 Is this correct? (y/N) y
 144 Really create? (y/N) y
 145 ----
 146
 147 TIP: At this point, GnuPG will start gathering entropy again, running an
 148      "find /" in the background is a good way to speed it up. When done it
 149      will print the sub key summary and return to the prompt. Note the ID
 150      "1584F206" of the subkey, we'll need that in step 4.
 151
 152 ----
 153 pub  4096R/612A0E98  created: 2016-04-05  expires: never       usage: SC
 154                      trust: ultimate      validity: ultimate
 155 sub  4096R/1584F206  created: 2016-04-05  expires: 2018-04-05  usage: S
 156 [ultimate] (1). Jo-Philipp Wich (LEDE Signing Key) <jo@mein.io>
 157 ----
 158
 159 TIP: Enter "save" to commit the new key pair and its sub key to disk, the
 160      GnuPG will automatically exit to the shell.
 161
 162 ----
 163 gpg> save
 164 ----
 165
 166 === 3) Put the key into a vault
 167
 168 At this point it is a good idea to make a *reliable and secure* backup
 169 of the +/tmp/signing/+ directory, I suggest burning it onto a CDROM or
 170 copying it onto a thumb drive which you can safely lock away or hide in
 171 your apartment :)
 172
 173 === 4) Export the private sub key only
 174
 175 We'll now export just the secret sub key since that is all we'll ever
 176 need to sign files. Use the sub key ID from step 2 followed by an
 177 exclamation mark to select the sub key to export:
 178
 179 ----
 180 $ gpg --homedir /tmp/signing --export-secret-subkeys 1584F206! \
 181    > /tmp/secret-signing-key.pgp
 182 $ file /tmp/secret-signing-key.pgp
 183 secret-signing-key.pgp: PGP\011Secret Key - 1024b created on Tue Apr  5
 184 16:08:15 2016 - RSA (Encrypt or Sign)
 185 ----
 186
 187 === 5) Import the secret signing sub key into your actual key store
 188
 189 You can now import the secret signing sub key on any machine you'll use
 190 for signing files in the future. To import the sub key file, pass it to
 191 +gpg --import+ and leave out the alternative homedir argument:
 192
 193 ----
 194 $ gpg --import /tmp/secret-signing-key.pgp
 195 gpg: key 612A0E98: secret key imported
 196 gpg: key 612A0E98: public key "Jo-Philipp Wich (LEDE Signing Key)
 197 <jo@mein.io>" imported
 198 gpg: Total number processed: 1
 199 gpg:               imported: 1  (RSA: 1)
 200 gpg:       secret keys read: 1
 201 gpg:   secret keys imported: 1
 202 ----
 203
 204 TIP: You can now issue a "gpg -K" to list all secret keys in your key store,
 205      you should see the key you've imported with a leading "sec#". The hash
 206      mark here indicates that the secret master key is missing, which is what
 207      we want.
 208
 209 ----
 210 $ gpg -K
 211 /home/jow/.gnupg/secring.gpg
 212  ---------------------------
 213 [...]
 214 sec#  4096R/612A0E98 2016-04-05
 215 uid                  Jo-Philipp Wich (LEDE Signing Key) <jo@mein.io>
 216 ssb   4096R/1584F206 2016-04-05
 217 ----
 218
 219 TIP: It is time to upload your public key part to a key server now so that
 220      others can easily fetch it by its fingerprint or your chosen mail
 221      address later on. For uploading use the primary key ID printed after
 222      the "sec#" word in the previous command.
 223
 224 ----
 225 $ gpg --keyserver hkp://pool.sks-keyservers.net --send-keys 612A0E98
 226 gpg: sending key 612A0E98 to hkp server pool.sks-keyservers.net
 227 ----
 228
 229 === 6) Delete original
 230
 231 Make sure once again that your backup of the +/tmp/signing+ directory is
 232 complete and readable, then remove the secret sub key file and the
 233 entire temporary signing directory:
 234
 235 ----
 236 $ rm -r /tmp/signing/
 237 $ rm /tmp/secret-signing-key.pgp
 238 ----
 239
 240 TIP: You're now done setting up a suitable signing key pair.
 241
 242 === 7) Finish
 243
 244 To export your public key in ASCII format use the following command,
 245 again with the primary ID you've already used for uploading the pubkey.
 246
 247 Make sure to provide a meaningful comment so that people looking at the
 248 key file know who it belongs to without having to inspect it using GPG
 249 utilities:
 250
 251 ----
 252 $ gpg --armor --export --no-version \
 253         --comment="Public key of Jo-Philipp Wich" 612A0E98
 254 ----
 255
 256 In order to sign a file with your signing sub key, use the command below:
 257
 258 ----
 259 $ gpg --no-version -a -b -u 612A0E98 \
 260         --comment="My signature for something" -o output.sig input.file
 261 ----
 262
 263 TIP: Use your key ID as filename when adding your public signing key to the
 264      repository:
 265
 266 ----
 267 $ cd keyring/gpg/
 268 $ gpg --armor --export --no-version \
 269   --comment="Public key of Me Myself" 612A0E98 > 612A0E98.asc
 270 $ git add 612A0E98.asc
 271 $ git commit -sm "Add my public key"
 272 $ git push origin master
 273 ----
 274
 275 == Generate _usign_ key pair
 276
 277 In order to generate an _usign_ key pair for use in LEDE release and package
 278 repositories, follow the steps below.
 279
 280 === 1) Obtain _usign_
 281
 282 Clone the _usign_ repository and compile it. Note that the compilation requires
 283 an installed +cmake+ to succeed.
 284
 285 ----
 286 $ git clone https://git.openwrt.org/project/usign.git
 287 $ cd usign/
 288 $ cmake .
 289 $ make
 290 ----
 291
 292 TIP: Run +./usign+ to check that the binary works.
 293
 294 ----
 295 $ ./usign
 296 Usage: ./usign <command> <options>
 297 Commands:
 298   -V:                   verify (needs at least -m and -p|-P)
 299   -S:                   sign (needs at least -m and -s)
 300   -F:                   print key fingerprint of public/secret key or signature
 301   -G:                   generate a new keypair
 302 Options:
 303   -c <comment>:         add comment to keys
 304   -m <file>:            message file
 305   -p <file>:            public key file (verify/fingerprint only)
 306   -P <path>:            public key directory (verify only)
 307   -q:                   quiet (do not print verification result, use return code only)
 308   -s <file>:            secret key file (sign/fingerprint only)
 309   -x <file>:            signature file (defaults to <message file>.sig)
 310 ----
 311
 312 === 2) Generate key pair
 313
 314 Instruct the +usign+ executable to generate a new key pair and provide a
 315 suitable comment to be able to identify the key file later on.
 316
 317 ----
 318 ./usign -G -c "LEDE usign key of Jo-Philipp Wich" \
 319   -s secret.key -p public.key
 320 ----
 321
 322 TIP: Store the +secret.key+ file in a *secure and reliable* location, you'll
 323      need it to sign package repositories in the future.
 324
 325 === 3) Add public key to the repository
 326
 327 Obtain the fingerprint of your public key with the +usign -F+ command and use
 328 it as filename for storing the pubkey in the +keyring.git+ repository:
 329
 330 ----
 331 $ ./usign -F -p public.key
 332 72a57f2191b211e0
 333 ----
 334
 335 TIP: Add the key to Git, using the fingerprint as filename:
 336
 337 ----
 338 $ cd keyring/usign/
 339 $ cp /some/where/public.key 72a57f2191b211e0
 340 $ git add 72a57f2191b211e0
 341 $ git commit -sm "Add my public usign key"
 342 $ git push origin master
 343 ----