Creating and Editing Key Categories

## 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 Key | Type | Description
--- | --- | ---
`background-color` | color | The background color to use. If missing, defaults to whichever background color is defined globally for list views.
`foreground-color` | color | The foreground color to use. If missing, defaults to whichever foreground color is defined globally for list views.
`font` | font | 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-bold` | boolean | 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-italic` | boolean | Analogous to `font-bold`, but for italic font style instead of bold.
`font-strikeout` | boolean | If `true`, draws a centered line over the font. Applied even if `font` is set.
`icon` | text | 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 Key | Type | If specified, filter matches when...
--- | --- | ---
`is-revoked` | boolean | the key has been revoked.
`match-context` | context[a] | the context in which this filter matches.
`is-expired` | boolean | the key is expired.
`is-disabled` | boolean | the key has been disabled (marked for not using) by the user. Ignored for S/MIME keys.
`is-root-certificate` | boolean | the key is a root certificate. Ignored for OpenPGP keys.
`can-encrypt` | boolean | the key can be used for encryption.
`can-sign` | boolean | the key can be used for signing.
`can-certify` | boolean | the key can be used for signing (certifying) other keys.
`can-authenticate` | boolean | the key can be used for authentication (e.g. as an TLS client certificate).
`is-qualified` | boolean | the key can be used to make Qualified Signatures (as defined by the German Digital Signature Law).
`is-cardkey` | boolean | the key material is stored on a smartcard (instead of on the computer).
`has-secret-key` | boolean | the secret key for this key pair is available.
`is-openpgp-key` | boolean | the key is an OpenPGP key (`true`), or an S/MIME key (`false`).
`was-validated` | boolean | 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`-validity` | validity | 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 )