Project:Gentoo-keys/First-Use

This is a short, "First USE" intro to using gkeys

First Use Intro

gkeys, much like git has a number of sub-commands which running gkeys -h will show the list of currently available ones.

With the install of gkeys, the gentoo-keys binary keyring was installed. This keyring holds the various gentoo release media keys and our new gkeys key used to sign the seed files we generate.

These key are listed under the category "gentoo" eg:

   $ gkeys list-key -C gentoo

to list all the keys in that category.

Developer keys and seed file

The ebuild also does a:

$ gkeys fetch-seed -C gentoo-devs

operation. This downloads and makes available all the gkey seeds of the gentoo developers. This list is not complete as there are a number of devs with conflicting or missing information in LDAP. Here is an excerpt from the logs:

   2015-01-05 09:14:43,109 gkey-ldap    INFO     Total number of seeds created........: 215
   2015-01-05 09:14:43,109 gkey-ldap    INFO     Seeds created... Saving file.........: /var/lib/gkeys/seeds/gentoo-devs.seeds.new
   2015-01-05 09:14:43,109 gkey-ldap    INFO     Total number of Dev's with GPG errors: 19

You can view the logs of the gentoo-devs.seeds file creation run at [1]

Currently both the keyid and fingerprint fields are to be filled in and they must match. For every keyid there must be a corresponding fingerprint listed. If not an error will be generated in the log and your seed info will not be put into the seeds file. The keyid field in LDAP will be dropped some time in the future and fingerprint listings only will be used. The seed file does not save the keyid data from LDAP, it saves only the fingerprint data. For OpenPGP V4 keys, the last 16 digits of the fingerprint are the long keyid. But as long as LDAP contains the keyid field, gkeys will use that data to check for matching the fingerprints.

Installing the gentoo-devs gpg keys

For those devs with a seed present in the gentoo-devs.seeds file. To install a seeds actual key:

 $ gkeys install-key -C gentoo-devs -n foo

simple breakdown:

   the -C, --category option specifies which category
   of seeds to use or which category of installed keys to use.

plus one of the following is needed:

   -n, --nick
   -N, --name
   -f, --fingerprint
   -K, --keys (the primary key fingerprint)

-n, --nick is most used/easiest for most gkeys operations. The seeds are stored under nick in the seeds file as well.

For many of gkeys sub-commnads, just specifying the -C, --category is enough for it to act on all seeds/keys.

eg:

 $ gkeys install-key -C gentoo-devs

Will install all gentoo-devs seeds in the gentoo-devs.seeds file.

Checking your/others key(s) meet GLEP 63 specs

To check if your (or any devs key(s)) passes the minimum GLEP 63 specification:

$ gkeys spec-check -C gentoo-devs -n foo

Or check the entire category by specifying only the -C category.

$ gkeys spec-check -C gentoo-devs

NOTE: gkeys will check all keys and subkeys found in the developers keyring. It will show pass/fail for any spec requirements, or True/False for non-spec requirements parameters and data in the key. It will display a final report card for each primary key with a final pass/fail result.

This is the summary of the current installed gentoo-devs keys/keyrings on my system:

 Found Failures:
 -------
   Revoked................: 10
   Invalid................: 0
   No Signing subkey......: 193  <== GLEP 63 requirement, fixable
   No Encryption subkey...: 41   <== for info only
   Algorithm..............: 0    <== GLEP 63 requirement
   Bit length.............: 114  <== GLEP 63 requirement
   Expiry.................: 244  <== info only, only some may be 
                                     relevant, fixable
   Expiry Warnings........: 0
   SPEC requirements......: 199  <== failed to pass spec
   =============================
   SPEC Approved..........: 16   <== passed spec, some devs have
                                     more than 1 key in this list.

So you can see, the majority of devs need to upgrade or fix/modify their GPG keys. Not all devs need to generate a new key to meet the GLEP 63 requirements. Many have their primary key set for signing capability, the GLEP specifies a dedicated signing sub-key. It is best to create a new signing subkey, this signing subkey will be used by default. An encryption subkey is not a GLEP requirement but is a good idea and needed to receive encrypted email/content.

Fixing your gpg key to meet GLEP 63 specs

For many of the devs keys, they only need the expiry date changed or need to add a signing subkey. Those are easily fixed without the need to create a new key.

Rather than go into detail here for each type of fix, I highly recommend the following webpage:

https://alexcabal.com/creating-the-perfect-gpg-keypair/

It is very detailed about creating a very secure gpg key flexible for laptop, desktop use... For adding a signing subkey, scroll down to the section

 "ADDING A NEW SIGNING SUBKEY"

After you have fixed your key or created a new one, update LDAP (for a new key, you will have to wait for me to update the seeds file (it is not fully automated yet), re-fetch and install your keys again, no need to remove the original). Then run

   $ gkeys refresh-key -C gentoo-devs

To update all gentoo-devs keys in the keyrings. (Your not the only one updating their key)

Runing gkeys as a user

If you wish to run gkeys strictly as a user for all operations. You can create and save copies of the gkeys.conf and gkeys-gen.conf in your users homedir in a .gkeys subdir.

   ~/.gkeys/

Edit these configs to suit your needs. gkeys will look for configs in that directory if it exists before using the ones installed in /etc/gkeys/

 (TODO: make it use stacking, so only some options may be overridden.
        make it stack system and user installed keyrings)

Then you can make a copy of /var/lib/gentoo/gkeys/keyrings/gentoo/ to your new keyrings location. From there you can fetch-seeds and install-keys, ... all as a user. There will be no need to perform many operations as root.

IRC and other help

You can find us for help in #gentoo-keys IRC channel to help fix your keys, or deal with any issues you have running gkeys or gkeys-gen. There is also several wiki pages (more to come, help appreciated) [3] and a copy of this (to be expanded) will be here [4]

Please keep in mind this is the initial release. We have disabled a few sub-commands which were not yet ready and will be in later releases. Plus there are several more features on our TODO list. But the primary functionality is there.

Please report bugs in bugzilla [2], project: Gentoo-keys

Links

 [1] http://dev.gentoo.org/~dolsen/gkey-logs/
 [2] http://bugs.gentoo.org/
 [3] https://wiki.gentoo.org/wiki/Project:Gentoo-keys