optools/gpg/kant/docs/kant.1.adoc

9.6 KiB
Raw Permalink Blame History

kant(1) Manual Page

NAME

KANT - Sign GnuPG/OpenPGP/PGP keys and notify the key owner(s)

SYNOPSIS

kant [OPTION] -k/--key <KEY_IDS|BATCHFILE>

OPTIONS

Keysigning (and keysigning parties) can be a lot of fun, and can offer someone with new keys a way into the WoT (Web-of-Trust). Unfortunately, they can be intimidating to those new to the experience. This tool offers a simple and easy-to-use interface to sign public keys (normal, local-only, and/or non-exportable), set owner trust, specify level of checking done, and push the signatures to a keyserver. It even supports batch operation via a CSV file. On successful completion, information about the keys that were signed and the key used to sign are saved to ~/.kant/cache/YYYY.MM.DD_HH.MM.SS.

-h, --help

Display brief help/usage and exit.

-k KEY_IDS|BATCHFILE, --key KEY_IDS|BATCHFILE

A single or comma-separated list of key IDs (see KEY ID FORMAT) to sign, trust, and notify. Can also be an email address. If -b/--batch is specified, this should instead be a path to the batch file (see BATCHFILE/Format).

-K KEY_ID, --sigkey KEY_ID

The key to use when signing other keys (see KEY ID FORMAT). The default key is automatically determined at runtime (it will be displayed in -h/--help output).

-t TRUSTLEVEL, --trust TRUSTLEVEL

The trust level to automatically apply to all keys (if not specified, KANT will prompt for each key). See BATCHFILE/TRUSTLEVEL for trust level notations.

-c CHECKLEVEL, --check CHECKLEVEL

The level of checking that was done to confirm the validity of ownership for all keys being signed. If not specified, the default is for KANT to prompt for each key we sign. See BATCHFILE/CHECKLEVEL for check level notations.

-l LOCAL, --local LOCAL

If specified, make the signature(s) local-only (i.e. non-exportable, dont push to a keyserver). See BATCHFILE/LOCAL for more information on local signatures.

-n, --no-notify

This requires some explanation. If you have MSMTP[1] installed and configured for the currently active user, then we will send out emails to recipients letting them know we have signed their key. However, if MSMTP is installed and configured but this flag is given, then we will NOT attempt to send emails. See MAIL for more information.

-s KEYSERVER(S), --keyservers KEYSERVER(S)

The comma-separated keyserver(s) to push to. The default keyserver list is automatically generated at runtime.

-m PROFILE, --msmtp-profile PROFILE

If specified, use the msmtp profile named PROFILE. If this is not specified, KANT first looks for an msmtp configuration named KANT (case-sensitive). If it doesnt find one, it will use the profile specified as the default profile in your msmtp configuration. See MAIL for more information.

-b, --batch

If specified, operate in batch mode. See BATCHFILE for more information.

-D GPGDIR, --gpgdir GPGDIR

The GnuPG configuration directory to use (containing your keys, etc.). The default is automatically generated at runtime, but will probably be /home/<yourusername>/.gnupg or similar.

-T, --testkeyservers

If specified, initiate a basic test connection with each set keyserver before anything else. Disabled by default.

KEY ID FORMAT

Key IDs can be specified in one of two ways. The first (and preferred) way is to use the full 160-bit (40-character, hexadecimal) key ID. A little known fact is the fingerprint of a key:

DEAD BEEF DEAD BEEF DEAD BEEF DEAD BEEF DEAD BEEF

is actually the full key ID of the primary key; i.e.:

DEADBEEFDEADBEEFDEADBEEFDEADBEEFDEADBEEF

The second way to specify a key, as far as KANT is concerned, is to use an email address. Do note that if more than one key is found that matches the email address given (and they usually are), you will be prompted to select the specific correct key ID anyways so its usually a better idea to have the owner present their full key ID/fingerprint right from the get-go.

BATCHFILE

Format

The batch file is a CSV-formatted (comma-delimited) file containing keys to sign and other information about them. It keeps the following format:

KEY_ID,TRUSTLEVEL,LOCAL,CHECKLEVEL,NOTIFY

For more information on each column, reference the appropriate sub-section below.

KEY_ID

See KEY ID FORMAT.

TRUSTLEVEL

The TRUSTLEVEL is specified by the following levels (you can use either the numeric or string representation):

-1 = Never
 0 = Unknown
 1 = Untrusted
 2 = Marginal
 3 = Full
 4 = Ultimate

It is how much trust to assign to a key, and the signatures that key makes on other keys.[2]

LOCAL

Whether or not to push to a keyserver. It can be either the numeric or string representation of the following:

0 = False
1 = True

If 1/True, KANT will sign the key with a local signature (and the signature will not be pushed to a keyserver or be exportable).[3]

CHECKLEVEL

The amount of checking that has been done to confirm that the owner of the key is who they say they are and that the key matches their provided information. It can be either the numeric or string representation of the following:

0 = Unknown
1 = None
2 = Casual
3 = Careful

It is up to you to determine the classification of the amount of checking you have done, but the following is recommended (it is the policy the author follows):

Unknown: The key is unknown and has not been reviewed

None: The key has been signed, but no confirmation of the
        ownership of the key has been performed (typically
        a local signature)

Casual: The key has been presented and the owner is either
          known to the signer or they have provided some form
          of non-government-issued identification or other
          proof (website, Keybase.io, etc.)

Careful: The same as Casual requirements but they have
          provided a government-issued ID and all information
          matches

Its important to check each key you sign carefully. Failure to do so may hurt others' trust in your key.[4]

MAIL

The mailing feature of KANT is very handy; it will let you send notifications to the owners of the keys you sign. This is encouraged because: 1.) its courteous to let them know where they can fetch the signature you just made on their key, 2.) its courteous to let them know if you did/did not push to a keyserver (some people dont want their keys pushed, and its a good idea to respect that wish), and 3.) the mailer also attaches the pubkey for the key you used to sign with, in case your key isnt on a keyserver, etc.

However, in order to do this since many ISPs block outgoing mail, one would typically use something like msmtp (http://msmtp.sourceforge.net/). Note that you dont even need msmtp to be installed, you just need to have msmtp configuration files set up via either /etc/msmtprc or ~/.msmtprc. KANT will parse these configuration files and use a purely pythonic implementation for sending the emails (see SENDING).

It supports templated mail messages as well (see TEMPLATES). It sends a MIME multipart email, in both plaintext and HTML formatting, for mail clients that may only support one or the other. It will also sign the email message using your signing key (see -K, --sigkey) and attach a binary (.gpg) and ASCII-armored (.asc) export of your pubkey.

SENDING

KANT first looks for ~/.msmtprc and, if not found, will look for /etc/msmtprc. If neither are found, mail notifications will not be sent and it will be up to you to contact the key owner(s) and let them know you have signed their key(s). If it does find either, it will use the first configuration file it finds and first look for a profile called "KANT" (without quotation marks). If this is not found, it will use whatever profile is specified for as the default profile (e.g. account default: someprofilename in the msmtprc).

TEMPLATES

KANT, on first run (even with a -h/--help execution), will create the default email templates (which can be found as ~/.kant/email.html.j2 and ~/.kant/email.plain.j2). These support templating via Jinja2 (http://jinja.pocoo.org/docs/2.9/templates/), and the following variables/dictionaries/lists are exported for your use:

* key - a dictionary of information about the recipient's key (see docs/REF.keys.struct.txt)
* mykey - a dictionary of information about your key (see docs/REF.keys.struct.txt)
* keyservers - a list of keyservers that the key has been pushed to (if an exportable/non-local signature was made)

And of course you can set your own variables inside the template as well (http://jinja.pocoo.org/docs/2.9/templates/#assignments).

SEE ALSO

gpg(1), gpgconf(1), msmtp(1)

RESOURCES

Authors web site: https://square-r00t.net/

Authors GPG information: https://square-r00t.net/gpg-info

COPYING

Copyright (C) 2017 Brent Saner.

Free use of this software is granted under the terms of the GPLv3 License.


2. For more information on trust levels and the Web of Trust, see: https://www.gnupg.org/gph/en/manual/x334.html and https://www.gnupg.org/gph/en/manual/x547.html
3. For more information on pushing to keyservers and local signatures, see: https://www.gnupg.org/gph/en/manual/r899.html#LSIGN and https://lists.gnupg.org/pipermail/gnupg-users/2007-January/030242.html
4. GnuPG documentation refers to this as "validity"; see https://www.gnupg.org/gph/en/manual/x334.html