Project Talk:Gentoo-keys/gkeys

gkeys -h
usage: gkeys [-h] [-c CONFIG] [-D {WARNING,INFO,FATAL,NOTSET,WARN,DEBUG,ERROR,CRITICAL}] [subcommand] [subcommand-option,...]

Gentoo-keys manager program

optional arguments: -h, --help           show this help message and exit -c CONFIG, --config CONFIG The path to an alternate config file -D {WARNING,INFO,FATAL,NOTSET,WARN,DEBUG,ERROR,CRITICAL}, --debug {WARNING,INFO,FATAL,NOTSET,WARN,DEBUG,ERROR,CRITICAL} The logging level to set for the logfile

Subcommands: Valid subcommands Additional help ---general---      - -- sign               Sign a file verify             File verification action keys-      --- check-key          Check keys actions import-key         Add a specified key to a specified keyring installed          Lists the installed key directories install-key        Install a key from the seed(s) search-key         Search for a key's seed field in the installed keys db    send-key            Uploads the selected key/s to the server list-key           Pretty-print the selected seed file or nick move-key           Rename an installed key refresh-key        Calls gpg with the --refresh-keys option remove-key         Remove an installed key spec-check         Check keys actions seeds      -- --- add-seed           Add or replace a key in the selected seed file(s) fetch-seed         Download the selected seed file(s) list-cats          List seed file definitions found in the config list-seed          Pretty-print the selected seed file(s) list-seedfiles     List seed files found in the configured seed directory move-seed          Move keys between seed files remove-seed        Remove a key from the selected seed file(s) update-seed        Downloads and installs the seeds of the selected category

CAUTION: adding UNTRUSTED keys can be HAZARDOUS to your system!

gkeys sign -h
usage: gkeys sign [-h] [-n NICK] [-N [NAME [NAME ...]]] [-r KEYDIR] [-f FINGERPRINT [FINGERPRINT ...]] [-F FILENAME [FILENAME ...]] [-k KEYRING]

Sign a file

optional arguments: -h, --help           show this help message and exit

Signing key info (one or more of nick, name, fingerprint as appropriate) -n NICK, --nick NICK The nick associated with the the key -N [NAME [NAME ...]], --name [NAME [NAME ...]] The name of the the key -f FINGERPRINT [FINGERPRINT ...], --fingerprint FINGERPRINT [FINGERPRINT ...] The fingerprint of the the key Target file to sign -F FILENAME [FILENAME ...], --file FILENAME [FILENAME ...] The path/URL to use for the (signed) file

gkeys verify -h
usage: gkeys verify [-h] [-d DESTINATION] [-n NICK] [-N [NAME [NAME ...]]] [-r KEYDIR] [-K [KEYS [KEYS ...]]] [-f FINGERPRINT [FINGERPRINT ...]] [-C CATEGORY] [-F FILENAME] [-s SIGNATURE] [-t]

File verification action. Note: If the specified key/keyring to verify against does not contain the key used to sign the file. It will Auto-search for the correct key in the installed keys db. And verify against the matching key.

optional arguments: -h, --help           show this help message and exit

gpg key options (optional, if none specified, it will auto-search) -n NICK, --nick NICK The nick associated with the the key -N [NAME [NAME ...]], --name [NAME [NAME ...]] The name of the the key -r KEYDIR, --keydir KEYDIR The keydir to use, update or search for/in -K [KEYS [KEYS ...]], --keys [KEYS [KEYS ...]] The name of the keyring to use for verification, etc. -f FINGERPRINT [FINGERPRINT ...], --fingerprint FINGERPRINT [FINGERPRINT ...] The fingerprint of the the key -C CATEGORY, --category CATEGORY The key or seed directory category to use or update

target file options (minimum -F is needed, others optional) -d DESTINATION, --dest DESTINATION The save destination for http, etc. type download operations -F FILENAME, --file FILENAME The path/URL to use for the (signed) file -s SIGNATURE, --signature SIGNATURE The path/URL to use with the signature -t, --timestamp      Turn on timestamp use. (records a timestamp file for the downloaded file)

gkeys check-key -h
usage: gkeys check-key [-h] [-n NICK] [-N [NAME [NAME ...]]] [-r KEYDIR] [-K [KEYS [KEYS ...]]] [-f FINGERPRINT [FINGERPRINT ...]] [-C CATEGORY] [-k KEYRING] [-i KEYID [KEYID ...]]

Check keys actions Performs basic validity checks on the key(s), checks expiry, and presence of a signing sub-key

optional arguments: -h, --help           show this help message and exit -n NICK, --nick NICK The nick associated with the the key -N [NAME [NAME ...]], --name [NAME [NAME ...]] The name of the the key -r KEYDIR, --keydir KEYDIR The keydir to use, update or search for/in -K [KEYS [KEYS ...]], --keys [KEYS [KEYS ...]] The name of the keyring to use for verification, etc. -f FINGERPRINT [FINGERPRINT ...], --fingerprint FINGERPRINT [FINGERPRINT ...] The fingerprint of the the key -C CATEGORY, --category CATEGORY The key or seed directory category to use or update -k KEYRING, --keyring KEYRING The name of the keyring to use for verification, etc. -i KEYID [KEYID ...], --keyid KEYID [KEYID ...] The long keyid of the gpg key to search for

gkeys import-key -h
usage: gkeys import-key [-h] [-n NICK] [-N [NAME [NAME ...]]] [-r KEYDIR] [-K [KEYS [KEYS ...]]] [-f FINGERPRINT [FINGERPRINT ...]] [-C CATEGORY] [-k KEYRING]

Add a specified key to a specified keyring

optional arguments: -h, --help           show this help message and exit source options -n NICK, --nick NICK The nick associated with the the key -N [NAME [NAME ...]], --name [NAME [NAME ...]] The name of the the key -r KEYDIR, --keydir KEYDIR The keydir to use, update or search for/in -K [KEYS [KEYS ...]], --keys [KEYS [KEYS ...]] The name of the keyring to use for verification, etc. -f FINGERPRINT [FINGERPRINT ...], --fingerprint FINGERPRINT [FINGERPRINT ...] The fingerprint of the the key -C CATEGORY, --category CATEGORY The source seed file (category) to use target option (optional, the seed contains a keydir field normally used as the target) -k KEYRING, --keyring KEYRING The name of the keyring to install it to

gkeys installed -h
usage: gkeys installed [-h] [-n NICK] [-N [NAME [NAME ...]]] [-r KEYDIR] [-K [KEYS [KEYS ...]]] [-f FINGERPRINT [FINGERPRINT ...]] [-C CATEGORY] [-k KEYRING]

Lists the installed key directories

optional arguments: -h, --help           show this help message and exit Minimum required is -C, --category -n NICK, --nick NICK The nick associated with the the key -N [NAME [NAME ...]], --name [NAME [NAME ...]] The name of the the key -r KEYDIR, --keydir KEYDIR The keydir to list -K [KEYS [KEYS ...]], --keys [KEYS [KEYS ...]] The name of the keyring to list -f FINGERPRINT [FINGERPRINT ...], --fingerprint FINGERPRINT [FINGERPRINT ...] The fingerprint of the the key -C CATEGORY, --category CATEGORY The key directory (category) to use -k KEYRING, --keyring KEYRING The name of the keyring to list

gkeys install-key -h
usage: gkeys install-key [-h] [-n NICK] [-N [NAME [NAME ...]]] [-r KEYDIR] [-K [KEYS [KEYS ...]]] [-f FINGERPRINT [FINGERPRINT ...]] [-C CATEGORY] [-k KEYRING] [-F FILENAME]

Install a key from the seed(s)

optional arguments: -h, --help           show this help message and exit Minimum -C, --category required (category only will install all keys in that seed-file) -n NICK, --nick NICK The nick associated with the the key -N [NAME [NAME ...]], --name [NAME [NAME ...]] The name of the the key -r KEYDIR, --keydir KEYDIR The keydir to use, update or search for/in -K [KEYS [KEYS ...]], --keys [KEYS [KEYS ...]] The name of the keyring to use for verification, etc. -f FINGERPRINT [FINGERPRINT ...], --fingerprint FINGERPRINT [FINGERPRINT ...] The fingerprint of the the key -C CATEGORY, --category CATEGORY The key or seed directory category to use or update -k KEYRING, --keyring KEYRING The name of the keyring to use for verification, etc. -F FILENAME, --file FILENAME The path/URL to use for the (signed) file

gkeys search-key -h
usage: gkeys search-key [-h] [-n NICK] [-N NAME] [-r KEYDIR] [-K [KEYS [KEYS ...]]] [-f FINGERPRINT [FINGERPRINT ...]] [-i KEYID [KEYID ...]] [-u [UID [UID ...]]] [-C CATEGORY] [-e] [-a]

Search for a key's seed in the installed keys db

optional arguments: -h, --help           show this help message and exit Minimum of one of the following -n NICK, --nick NICK The nick associated with the the key -N NAME, --name NAME The name of the the key -r KEYDIR, --keydir KEYDIR The keydir to use, update or search for/in -K [KEYS [KEYS ...]], --keys [KEYS [KEYS ...]] The name of the keyring to use for verification, etc. -f FINGERPRINT [FINGERPRINT ...], --fingerprint FINGERPRINT [FINGERPRINT ...] The fingerprint of the the key -i KEYID [KEYID ...], --keyid KEYID [KEYID ...] The long keyid of the gpg key to search for -u [UID [UID ...]], --uid [UID [UID ...]] The user ID, gpg key uid -C CATEGORY, --category CATEGORY The key or seed directory category to use or update Search filter options -e, --exact          Use CASE matching in searches -a, --all            Match all inputs arguments in searches

gkeys send-key -h
usage: gkeys send-key [-h] [-n NICK] [-N NAME] [-r KEYDIR] [-K [KEYS [KEYS ...]]] [-f FINGERPRINT [FINGERPRINT ...]] [-i KEYID [KEYID ...]] [-u [UID [UID ...]]] [-C CATEGORY] [-e] [-a]

Uploads the selected key/s to the server

optional arguments: -h, --help           show this help message and exit Minimum of one of the following -n NICK, --nick NICK The nick associated with the the key -N NAME, --name NAME The name of the the key -r KEYDIR, --keydir KEYDIR The keydir to use, update or search for/in -K [KEYS [KEYS ...]], --keys [KEYS [KEYS ...]] The name of the keyring to use for verification, etc. -f FINGERPRINT [FINGERPRINT ...], --fingerprint FINGERPRINT [FINGERPRINT ...] The fingerprint of the the key -i KEYID [KEYID ...], --keyid KEYID [KEYID ...] The long keyid of the gpg key to search for -u [UID [UID ...]], --uid [UID [UID ...]] The user ID, gpg key uid -C CATEGORY, --category CATEGORY The key or seed directory category to use or update Search filter options -e, --exact          Use CASE matching in searches -a, --all            Match all inputs arguments in searches

gkeys list-key -h
usage: gkeys list-key [-h] [-n NICK] [-N [NAME [NAME ...]]] [-r KEYDIR] [-K [KEYS [KEYS ...]]] [-f FINGERPRINT [FINGERPRINT ...]] [-C CATEGORY] [-k KEYRING] [-g GPGSEARCH] [-i KEYID [KEYID ...]]

Pretty-print the selected seed file or nick

optional arguments: -h, --help           show this help message and exit Minimum of one of the following options -n NICK, --nick NICK The nick associated with the the key -N [NAME [NAME ...]], --name [NAME [NAME ...]] The name of the the key -r KEYDIR, --keydir KEYDIR The keydir to use, update or search for/in -K [KEYS [KEYS ...]], --keys [KEYS [KEYS ...]] The name of the keyring to use for verification, etc. -f FINGERPRINT [FINGERPRINT ...], --fingerprint FINGERPRINT [FINGERPRINT ...] The fingerprint of the the key -C CATEGORY, --category CATEGORY The key or seed directory category to use or update -k KEYRING, --keyring KEYRING The name of the keyring to use for verification, etc. -g GPGSEARCH, --gpgsearch GPGSEARCH Do a gpg search operations, rather than a gkey search -i KEYID [KEYID ...], --keyid KEYID [KEYID ...] The long keyid of the gpg key to search for

gkeys move-key -h
usage: gkeys move-key [-h] [-n NICK] [-N [NAME [NAME ...]]] [-r KEYDIR] [-K [KEYS [KEYS ...]]] [-f FINGERPRINT [FINGERPRINT ...]] [-C CATEGORY] [-k KEYRING] [-d DESTINATION]

Rename an installed key

optional arguments: -h, --help           show this help message and exit Source options -n NICK, --nick NICK The nick associated with the the key -N [NAME [NAME ...]], --name [NAME [NAME ...]] The name of the the key -r KEYDIR, --keydir KEYDIR The keydir to use, update or search for/in -K [KEYS [KEYS ...]], --keys [KEYS [KEYS ...]] The name of the keyring to use for verification, etc. -f FINGERPRINT [FINGERPRINT ...], --fingerprint FINGERPRINT [FINGERPRINT ...] The fingerprint of the the key -C CATEGORY, --category CATEGORY The key or seed directory category to use or update -k KEYRING, --keyring KEYRING The name of the keyring to use for verification, etc. Target options -d DESTINATION, --dest DESTINATION The destination for move, copy, create operations

gkeys refresh-key -h
usage: gkeys refresh-key [-h] [-n NICK] [-N [NAME [NAME ...]]] [-r KEYDIR] [-K [KEYS [KEYS ...]]] [-f FINGERPRINT [FINGERPRINT ...]] [-C CATEGORY] [-k KEYRING] [-i KEYID [KEYID ...]]

Calls gpg with the --refresh-keys option for in place updates of the installed keys

optional arguments: -h, --help           show this help message and exit Minimum of one of the following options -n NICK, --nick NICK The nick associated with the the key -N [NAME [NAME ...]], --name [NAME [NAME ...]] The name of the the key -r KEYDIR, --keydir KEYDIR The keydir to use, update or search for/in -K [KEYS [KEYS ...]], --keys [KEYS [KEYS ...]] The name of the keyring to use for verification, etc. -f FINGERPRINT [FINGERPRINT ...], --fingerprint FINGERPRINT [FINGERPRINT ...] The fingerprint of the the key -C CATEGORY, --category CATEGORY The key or seed directory category to use or update -k KEYRING, --keyring KEYRING The name of the keyring to use for verification, etc. -i KEYID [KEYID ...], --keyid KEYID [KEYID ...] The long keyid of the gpg key to search for

gkeys remove-key -h
usage: gkeys remove-key [-h] [-n NICK] [-N [NAME [NAME ...]]] [-r KEYDIR] [-K [KEYS [KEYS ...]]] [-f FINGERPRINT [FINGERPRINT ...]] [-C CATEGORY] [-k KEYRING]

Remove an installed key

optional arguments: -h, --help           show this help message and exit Minimum of one of the following options, recommend -C and one other -n NICK, --nick NICK The nick associated with the the key -N [NAME [NAME ...]], --name [NAME [NAME ...]] The name of the the key -r KEYDIR, --keydir KEYDIR The keydir to use, update or search for/in -K [KEYS [KEYS ...]], --keys [KEYS [KEYS ...]] The name of the keyring to use for verification, etc. -f FINGERPRINT [FINGERPRINT ...], --fingerprint FINGERPRINT [FINGERPRINT ...] The fingerprint of the the key -C CATEGORY, --category CATEGORY The key or seed directory category to use or update -k KEYRING, --keyring KEYRING The name of the keyring to use for verification, etc.

gkeys spec-check -h
usage: gkeys spec-check [-h] [-n NICK] [-N [NAME [NAME ...]]] [-r KEYDIR] [-K [KEYS [KEYS ...]]] [-f FINGERPRINT [FINGERPRINT ...]] [-C CATEGORY] [-k KEYRING] [-i KEYID [KEYID ...]]

Check if keys meet specifications requirements

optional arguments: -h, --help           show this help message and exit -n NICK, --nick NICK The nick associated with the the key -N [NAME [NAME ...]], --name [NAME [NAME ...]] The name of the the key -r KEYDIR, --keydir KEYDIR The keydir to use, update or search for/in -K [KEYS [KEYS ...]], --keys [KEYS [KEYS ...]] The name of the keyring to use for verification, etc. -f FINGERPRINT [FINGERPRINT ...], --fingerprint FINGERPRINT [FINGERPRINT ...] The fingerprint of the the key -C CATEGORY, --category CATEGORY The key or seed directory category to use or update -k KEYRING, --keyring KEYRING The name of the keyring to use for verification, etc. -i KEYID [KEYID ...], --keyid KEYID [KEYID ...] The long keyid of the gpg key to search for

gkeys add-seed -h
usage: gkeys add-seed [-h] [-n NICK] [-N [NAME [NAME ...]]] [-r KEYDIR] [-K [KEYS [KEYS ...]]] [-f FINGERPRINT [FINGERPRINT ...]] [-C CATEGORY] [-u [UID [UID ...]]]

Add or replace a key in the selected seed file(s)

optional arguments: -h, --help           show this help message and exit Mandatory -n NICK, --nick NICK The nick associated with the the key -N [NAME [NAME ...]], --name [NAME [NAME ...]] The name of the the key -r KEYDIR, --keydir KEYDIR The destination keydir for the installed key -f FINGERPRINT [FINGERPRINT ...], --fingerprint FINGERPRINT [FINGERPRINT ...] The fingerprint of the the key -C CATEGORY, --category CATEGORY The seed file name (category) to update Optional -u [UID [UID ...]], --uid [UID [UID ...]] The user ID, gpg key uid

gkeys fetch-seed -h
usage: gkeys fetch-seed [-h] [-n NICK] [-F FILENAME] [-C CATEGORY] [-d DESTINATION] [-s SIGNATURE] [-t]

Download the selected seed file(s)

optional arguments: -h, --help           show this help message and exit Minimum -C, --category required -n NICK, --nick NICK The nick associated with the the key -F FILENAME, --file FILENAME The path/URL to use for the (signed) file -C CATEGORY, --category CATEGORY The key or seed directory category to use or update -d DESTINATION, --dest DESTINATION The destination for move, copy, create operations -s SIGNATURE, --signature SIGNATURE The path/URL to use for the signature -t, --timestamp      Turn on timestamp use

gkeys list-cats -h
usage: gkeys list-cats [-h]

List seed file definitions found in the config

optional arguments: -h, --help show this help message and exit

gkeys list-seed -h
usage: gkeys list-seed [-h] [-n NICK] [-N [NAME [NAME ...]]] [-r KEYDIR] [-K [KEYS [KEYS ...]]] [-f FINGERPRINT [FINGERPRINT ...]] [-C CATEGORY] [-F FILENAME]

Pretty-print the selected seed file(s)

optional arguments: -h, --help           show this help message and exit -n NICK, --nick NICK The nick associated with the the key -N [NAME [NAME ...]], --name [NAME [NAME ...]] The name of the the key -r KEYDIR, --keydir KEYDIR The keydir to use, update or search for/in -K [KEYS [KEYS ...]], --keys [KEYS [KEYS ...]] The name of the keyring to use for verification, etc. -f FINGERPRINT [FINGERPRINT ...], --fingerprint FINGERPRINT [FINGERPRINT ...] The fingerprint of the the key -C CATEGORY, --category CATEGORY The seed file name (category) to list -F FILENAME, --file FILENAME The path to use for the seed file

gkeys list-seedfiles -h
usage: gkeys list-seedfiles [-h]

List seed files found in the configured seed directory

optional arguments: -h, --help show this help message and exit

gkeys move-seed -h
usage: gkeys move-seed [-h] [-n NICK] [-N [NAME [NAME ...]]] [-r KEYDIR] [-K [KEYS [KEYS ...]]] [-f FINGERPRINT [FINGERPRINT ...]] [-C CATEGORY] [-d DESTINATION]

Move keys between seed files

optional arguments: -h, --help           show this help message and exit -n NICK, --nick NICK The nick associated with the the key -N [NAME [NAME ...]], --name [NAME [NAME ...]] The name of the the key -r KEYDIR, --keydir KEYDIR The keydir to use, update or search for/in -K [KEYS [KEYS ...]], --keys [KEYS [KEYS ...]] The name of the keyring to use for verification, etc. -f FINGERPRINT [FINGERPRINT ...], --fingerprint FINGERPRINT [FINGERPRINT ...] The fingerprint of the the key -C CATEGORY, --category CATEGORY The key or seed directory category to use or update -d DESTINATION, --dest DESTINATION The destination for move, copy, create operations

gkeys remove-seed -h
usage: gkeys remove-seed [-h] [-n NICK] [-N [NAME [NAME ...]]] [-r KEYDIR] [-K [KEYS [KEYS ...]]] [-f FINGERPRINT [FINGERPRINT ...]] [-C CATEGORY]

Remove a seed from the selected seed file

optional arguments: -h, --help           show this help message and exit -n NICK, --nick NICK The nick associated with the the seed -N [NAME [NAME ...]], --name [NAME [NAME ...]] The name of the the seed, key -r KEYDIR, --keydir KEYDIR The keydir to search for -K [KEYS [KEYS ...]], --keys [KEYS [KEYS ...]] The name of the keyring to use for verification, etc. -f FINGERPRINT [FINGERPRINT ...], --fingerprint FINGERPRINT [FINGERPRINT ...] The fingerprint of the the key -C CATEGORY, --category CATEGORY The seed file name (category) to update

Keyring and Seed file Categories
Keyrings in gkeys are organized into categories.
 * Each category can contain one or more keyrings.
 * Each keyring can contain one or more gpg key.

All gkeys operations revolve around the use of a -C, --category and as such is a required option for all actions.

For security reasons, most keyrings are separated into individual keyrings and not grouped together into one keyring.

Categories

 * gentoo This is the collections of release media seeds, keys


 * gentoo-devs This is the collection of active Gentoo developers seeds, keys


 * sign This is a locally defined category used to contain the keyrings capable of signing various objects.  Normally gpg uses ~/.gnupg/ for these.  Since gkeys wraps gpg commands with it's own structure of keyrings, this allows the definition of several individual keyrings which are capable of signing files, objects.  It uses the same syntax as other gkeys commands, providing a consistent interface.  eg:


 *   It is possible to create your own keyring category and create seed files and binary keyrings for use with gkeys.  They must be configured in the gkeys.conf file.  See the [seeds], [seedurls], [verify-seeds] sections of your gkeys.conf.

Keyrings

 * app-crypt/gentoo-keys Binary keyring installed as a dependency of gkeys. This is the "gentoo" category keyring which contains the release media gpg keys used by the infrastructure and Gentoo-keys teams.  These are the keys used to sign various release medi files, stages, iso's.


 * app-crypt/gentoo-devs-keys Not yet distributed as a binary keyring package.  You must install the keys yourself using the seed file.


 * app-crypt/  It is possible to create and distribute other keyrings for use with gkeys.  An example would be a keyring used to validate an overlays ebuild tree.