Project:Gentoo-keys/First-Use

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

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. The ebuild also does a:

$ gkeys fetch-seeds -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.

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.

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

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

Or the entire category by specifying on the -C category.

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 No Encryption subkey...: 41  <== for info only Algorithm..............: 0   <== GLEP 63 requirement Bit length.............: 114 <== GLEP 63 requirement Expiry.................: 244 <== info only, only some are relevant 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.

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 buzilla [2], project: Gentoo-keys

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