Creating and Editing Key Categories

Kleopatra allows the user to configure the visual appearance of keys based on a concept called Key Categories. Key Categories are also used to filter the list of certificates. This section describes how you can edit the available categories and add new ones.

When trying to find the category a key belongs to, Kleopatra tries to match the key to a sequence of key filters, configured in the libkleopatrarc. The first one to match defines the category, based on a concept of specificity, explained further below.

Each key filter is defined in a config group named Key Filter #n, where n is a number, starting from 0.

The only mandatory keys in a Key Filter #n group are Name, containing the name of the category as displayed in the config dialog, and id, which is used as a reference for the filter in other configuration sections (such as View #n).

Table 6.1, “Key-Filter Configuration Keys Defining Display Properties” lists all keys that define the display properties of keys belonging to that category (i.e. those keys that can be adjusted in the config dialog), whereas Table 6.2, “Key-Filter Configuration Keys Defining Filter Criteria” lists all keys that define the criteria the filter matches keys against.

Table 6.1. Key-Filter Configuration Keys Defining Display Properties

Config KeyTypeDescription
background-colorcolor The background color to use. If missing, defaults to whichever background color is defined globally for list views.
foreground-colorcolor The foreground color to use. If missing, defaults to whichever foreground color is defined globally for list views.
fontfont The custom font to use. The font will be scaled to the size configured for list views, and any font attributes (see below) will be applied.
font-boldboolean If set to true and font is not set, uses the default list view font with bold font style added (if available). Ignored if font is also present.
font-italicboolean Analogous to font-bold, but for italic font style instead of bold.
font-strikeoutboolean If true, draws a centered line over the font. Applied even if font is set.
icontext The name of an icon to show in the first column. Not yet implemented.

Table 6.2. Key-Filter Configuration Keys Defining Filter Criteria

Config KeyTypeIf specified, filter matches when...
is-revokedbooleanthe key has been revoked.
match-context context[a] the context in which this filter matches.
is-expiredbooleanthe key is expired.
is-disabledboolean the key has been disabled (marked for not using) by the user. Ignored for S/MIME keys.
is-root-certificateboolean the key is a root certificate. Ignored for OpenPGP keys.
can-encryptboolean the key can be used for encryption.
can-signboolean the key can be used for signing.
can-certifyboolean the key can be used for signing (certifying) other keys.
can-authenticateboolean the key can be used for authentication (e.g. as an TLS client certificate).
is-qualifiedboolean the key can be used to make Qualified Signatures (as defined by the German Digital Signature Law).
is-cardkeyboolean the key material is stored on a smartcard (instead of on the computer).
has-secret-keyboolean the secret key for this key pair is available.
is-openpgp-keyboolean the key is an OpenPGP key (true), or an S/MIME key (false).
was-validatedboolean the key has been validated.
prefix-ownertrust validity[b] the key has exactly (prefix = is), has anything but (prefix = is-not), has at least (prefix = is-at-least), or has at most (prefix = is-at-most) the ownertrust given as the value of the config key. If more than one prefix-ownertrust keys (with different prefix values) are present in a single group, the behavior is undefined.
prefix-validityvalidity Analogous to prefix-ownertrust, but for key validity instead of ownertrust.

[a] Context is an enumeration with the following allowed values: appearance, filtering and any.

[b] Validity is an (ordered) enumeration with the following allowed values: unknown, undefined, never, marginal, full, ultimate. See the GPG and GpgSM manuals for a detailed explanation.


Note

Some of the more interesting criteria, such as is-revoked or is-expired will only work on validated keys, which is why, by default, only validated keys are checked for revocation and expiration, although you are free to remove these extra checks.

In addition to the config keys listed above, a key filter may also have an id and match-contexts.

Using the filter's id, which defaults to the filter's config group name if not given or empty, you can reference the key filter elsewhere in the configuration, e.g. in Kleopatra's View configurations. The id is not interpreted by Kleopatra, so you can use any string you like, as long as it's unique.

The match-contexts limits the applicability of the filter. Two contexts are currently defined: The appearance context is used when defining coloring and font properties for the views. The filtering context is used to selectively include (and exclude) certificate from views. any can be used to signify all currently defined contexts, and is the default if match-contexts is not given, or otherwise produces no contexts. This ensures that no key filter can end up dead, i.e. with no contexts to apply it in.

The format of the entry is a list of tokens, separated by non-word characters. Each of the tokens is optionally prefixed by an exclamation point (!), indicating negation. The tokens act in order on an internal list of contexts, which starts out empty. This is best explained by an example: any !appearance is the same as filtering, and appearance !appearance is producing the empty set, as is !any. However, the last two will be internally replaced by any, since they produce no contexts at all.

In general, criteria not specified (i.e. the config entry is not set) are not checked for. If a criterion is given, it is checked for and must match for the filter as a whole to match, i.e. the criteria are AND'ed together.

Each filter has an implied specificity that is used to rank all matching filters. The more specific filter wins over less specific ones. If two filters have the same specificity, the one that comes first in the config file wins. A filter's specificity is proportional to the number of criteria it contains.

Example 6.1. Examples of key filters

To check for all expired, but non-revoked root certificates, you would use a key filter defined as follows:

[Key Filter #n]
Name=expired, but not revoked
was-validated=true
is-expired=true
is-revoked=false
is-root-certificate=true
; ( specificity 4 )

To check for all disabled OpenPGP keys (not yet supported by Kleopatra) with ownertrust of at least marginal, you would use:

[Key Filter #n]
Name=disabled OpenPGP keys with marginal or better ownertrust
is-openpgp=true
is-disabled=true
is-at-least-ownertrust=marginal
; ( specificity 3 )