Creating and Editing Key Categories

Kleopatra allows the user to configure the visual appearance of keys based on a concept called Key Categories. 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.

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

The only mandatory key in a Key Filter #n group is Name, containing the name of the category as displayed in the config dialog.

Table 6.1 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 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.
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).
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 (see Certificates->Validate (Shift+F5)).
prefix-ownertrust validity[a] 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] 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 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.

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

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