The Kleopatra Handbook
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
Kleopatra is a tool for managing X.509 certificates.
Table of Contents
List of Tables
List of Examples
Kleopatra is the KDE tool for managing X.509 certificates in the GpgSM keybox and for retrieving certificates from LDAP servers.
Kleopatra can be started from KMail's menu, as well as from the command line. The Kleopatra executable is named kleopatra.
This program is named after Cleopatra, a famous female Egyptian pharaoh that lived at the time of Julius Caesar, whom she is said to have had an intimate relationship with.
The name was chosen since this program originates from the Ägypten Projects (Ägypten is German for Egypt). Kleopatra is the German spelling of Cleopatra.
Kleopatra's main function is to display and edit the contents of the local keybox, which is similar to GPG's concept of keyrings, albeit one should not stretch this analogy too much.
The main window is divided into the large key listing area, the menubar and the search bar on top, and a statusbar at the bottom.
Each line in the key list corresponds to one certificate, identified by the so-called Subject DN. DN is an acronym for “Distinguished Name”, a hierarchical identifier, much like a filesystem path with an unusual syntax, that is supposed to globally uniquely identify a given certificate.
To be valid, and thus usable, (public) keys need to be signed by a CA (Certification Authority). These signatures are called certificates, but usually the terms “certificate” and “(public) key” are used interchangeably, and we will not distinguish between them in this manual either, except when explicitly noted. The name of the CA which issued the certificate (its DN) is shown in the Issuer DN column.
CAs must in turn be signed by other CAs to be valid. Of course, this must end somewhere, so the top-level CA (root-CA) signs its key with itself (this is called a self-signature). Root certificates thus need to be assigned validity (commonly called trust) manually, e.g. after comparing the fingerprint with the one on the website of the CA. This is typically done by the system administrator or the vendor of a product using certificates, but can be done by the user via GpgSM's command line interface.
To see which of the certificates are root certificates, you can either compare Subject DN and Issuer DN, or you switch to hierarchical keylist mode with ->.
You can see the details of any certificate by double-clicking it or using ->. This opens a dialog that shows the most common properties of the certificate, its certificate chain (i.e. the chain of issuers up to the root-CA), and a dump of all information the backend is able to extract from the certificate.
If you change the keybox without using Kleopatra (e.g. using GpgSM's command line interface), you can refresh the view with -> (F5).
Since validating a key may take some time (e.g. CRLs might need to be fetched), the normal keylisting does not attempt to check the validity of keys. For this, -> (Shift+F5), a special variant of -> (F5), is provided. It either checks the selected certificates, or all keys if none are selected.
Most of the time, you will acquire new certificates by verifying signatures in emails, since certificates are embedded in the signatures made using them most of the time. However, if you need to send a mail to someone you have not yet had contact with, you need to fetch the certificate from an LDAP directory (although GpgSM can do this automatically), or from a file. You also need to import your own certificate after receiving the CA answer to your certification request.
To search for a certificate in an LDAP directory, switch the dropdown menu of the search bar from in Local Certificates to in External Certificates, enter some text (e.g. the name of the person you want the certificate for) into the line edit, and click on the Find icon. The results will be displayed in the key list below the search bar, where you can select certificates to either look at them with -> or download them with -> into the local keybox. Note that you can also download the certificate from the details dialogue, using the Import to Local button.
You can configure the list of LDAP servers to search in the Directory Services page of Kleopatra's configure dialogue.
If you received the certificate as a file, try ->. GpgSM needs to understand the format of the certificate file; please refer to GpgSM's manual for a list of supported file formats.
If you did not create your keypair with GpgSM, you also need to manually import the public key (as well as the secret key) from the PKCS#12 file you got from the CA. You can do this on the command line with kleopatra or from within Kleopatra with ->, just as you would to for “normal” certificates.--import-certificate filename
Would you like to make a comment or contribute an update to this page?
Send feedback to the KDE Docs Team
The menu item -> starts the certificate-request-creating wizard which will guide you through a number of steps to create a certificate request; this request can, on the last page of the wizard, either be sent to a certificate authority (CA) to be signed or saved to a file (for example to a floppy, so it can be shipped to the CA).
Whenever you are done with a step in the wizard, press to go to the next step (or to review steps that are already completed). The certificate request creation can be cancelled at any time by pressing the button.
The first step in the wizard is to type in your personal data for the certificate. The fields to fill out are:
Name: Your name;
Location:The town or city in which you live;
Organisation:The organisation you represent (for example, the company you work for);
Department:The organisational unit you are in (for example, "Logistics");
Country code:The two letter code for the country in which you are living (for example, "UK");
Email address:Your email address; be sure to type this in correctly—this will be the address people will be sending mail to when they use your certificate.
The next step in the wizard is to select whether to store the certificate in a file or send it directly to a CA. You will have to specify the filename or email address to send the certificate request to.
Would you like to make a comment or contribute an update to this page?
Send feedback to the KDE Docs Team
In addition to list and validate, search and import certificates and creating new ones, Kleopatra also has some less often used functions that help you manage your local keybox.
These functions include deleting certificates from the local keybox with -> (Delete), as well as manual handling of CRLs (->, ->, ->).
Would you like to make a comment or contribute an update to this page?
Send feedback to the KDE Docs Team
Would you like to make a comment or contribute an update to this page?
Send feedback to the KDE Docs Team
Creates a new key pair (public and private) and allows to send the public part to a certification authority (CA) for signing. The resulting certificate is then sent back to you, or stored in an LDAP server for you to download into your local keybox, where you can use it to sign and decrypt mails.
This mode of operation is called “decentralised key generation”, since all keys are created locally. Kleopatra (and GpgSM) do not support “centralised key generation” directly, but you can import the public/secret key bundle that you receive from the CA in PKCS#12 format via ->.
Exports the selected certificates into a file.
This exports only the public keys, even if the secret key is available. Use -> to export both public and secret keys into a file, but note that this is almost always a bad idea.
Exports both the public and the secret key to a (PKCS#12) file.
It should rarely be necessary to use this function, and if it is, it should be carefully planned. Planning the migration of a secret key involves choice of transport media and secure deletion of the key data on the old machine, as well as the transport medium, among other things.
Imports certificates and/or secret keys from files into the local keybox.
The format of the certificate file must be supported by GpgSM. Please refer to the GpgSM manual for a list of supported formats.
Lets you manually import CRLs from files.
Normally, Certificate Revocation Lists (CRLs) are handled transparently by the backend, but it can sometimes be useful to import a CRL manually into the local CRL cache.
For CRL import to work, the dirmngr tool must be in the search PATH. If this menu item is disabled, you should contact the system administrator and ask them to install dirmngr.
You can view the contents of the local CRL cache from the menu item ->. This will display a dialogue with information about the CRLs in the cache and the fingerprints of the certificates in each CRL.
Terminates Kleopatra.
Redisplays the selected certificates or refreshes the certificate list.
If there are selected certificates, the refresh operation is restricted to those selected entries.
If a query result (either remote or local) is currently displayed, the query is re-issued and the new results are displayed in place of the old ones.
If no query has been performed, the whole keybox contents is re-fetched and re-displayed.
You can use this if you have changed the contents of the keybox by other means than Kleopatra (e.g. by using GpgSM's command line interface).
Stops (cancels) all pending operations, e.g. a search or a download.
Depending on the server used, cancelling a remote search can block Kleopatra for a few seconds while waiting for the backend to complete the procedure. This is normal and expected behaviour.
Shows the details of the currently selected certificate.
This function is also available by double-clicking the corresponding item in the list view directly.
Toggles between hierarchical and flat keylist mode.
In hierarchical mode, certificates are arranged in issuer/subject relation, so it is easy to see to which certification hierarchy a given certificate belongs, but a given certificate is harder to find initially (though you can of course use the search bar).
In flat mode, all certificates are displayed in a flat list, sorted alphabetically. In this mode, a given certificate is easy to find, but it is not directly clear which root certificate it belongs to.
(This function is only available when -> is on.)
Expands all list items in the certificate list view, i.e. makes all items visible.
This is the default when entering hierarchical keylist mode.
You can still expand and collapse each individual item by itself, of course.
(This function is only available when -> is on.)
Collapses all list items in the certificate list view, i.e. hides all but the top-level items.
You can still expand and collapse each individual item by itself, of course.
Would you like to make a comment or contribute an update to this page?
Send feedback to the KDE Docs Team
Validates selected (or all) keys.
This is similar to -> (F5), but performs a validation of the (selected) keys. Validation here means that all relevant CRLs are fetched, and the certificate chain is checked for correctness. As a result, invalid or expired keys will be marked according to your colour and font preferences set in the Appearance page of Kleopatra's configure dialogue.
You can only rely on information from validated keys, and, since any of them may be revoked at any time, even validation is only ever a snapshot of the current state of the local keyring. This is why the backend normally performs such checks whenever the keys are used (e.g. for signing, signature verification, encryption or decryption).
Fetches the current CRLs for all selected keys, even though they would normally not be fetched when using the key.
This function only has an effect on certificates which define a CRL distribution point. Depending on the backend used, certificates configured to perform checks using OCSP will not be updated.
You may use this e.g. if you have sideband knowledge that a key has been revoked, and you want the backend to reflect this now instead of relying on this to automatically happen at the next scheduled CRL update.
Excessive use of this function might put a high load on your provider's or company's network, since CRLs of large organisations can be surprisingly big (several megabytes are not uncommon).
Use this function scarcely.
Deletes selected certificate(s) from the local keyring.
Use this function to remove unused keys from your local keybox. However, since certificates are typically attached to signed emails, verifying an email might result in the key just removed to pop back into the local keybox. So it is probably best to avoid using this function as much as possible. When you are lost, use the search bar or the -> function to regain control over the lot of certificates.
Downloads the selected certificate(s) from the LDAP to the local keybox.
Would you like to make a comment or contribute an update to this page?
Send feedback to the KDE Docs Team
Clears the GpgSM CRL cache.
You probably never need this. You can force a refresh of the CRL cache by selecting all certificates and using -> instead.
Shows the detailed contents of the GpgSM CRL cache.
Would you like to make a comment or contribute an update to this page?
Send feedback to the KDE Docs Team
Starts KWatchGnuPG
Would you like to make a comment or contribute an update to this page?
Send feedback to the KDE Docs Team
Toggles the visibility of the bottom status bar.
Opens the standard KDE shortcut configuration dialogue, where you can assign and re-assign keyboard shortcuts for all menu items.
Opens Kleopatra's configure dialogue.
See Chapter 5, Configuring Kleopatra for more details.
Opens a dialogue that allows you to configure every aspect of GpgSM and other backend modules.
This dialogue is dynamically built from the output of the GpgConf utility and may thus change when backend modules are updated.
Would you like to make a comment or contribute an update to this page?
Send feedback to the KDE Docs Team
The menu contains the standard KDE help menu.
Invokes the KDE Help system starting at the Kleopatra help pages. (this document).
Changes the mouse cursor to a combination arrow and question mark. Clicking on items within Kleopatra will open a help window (if one exists for the particular item) explaining the item's function.
Opens the Bug report dialogue where you can report a bug or request a “wishlist” feature.
This will display version and author information.
This displays the KDE version and other basic information.
Would you like to make a comment or contribute an update to this page?
Send feedback to the KDE Docs Team
Would you like to make a comment or contribute an update to this page?
Send feedback to the KDE Docs Team
Only the options specific to Kleopatra are listed here. As with all KDE applications, you can get a complete list of options by issuing the command kleopatra .--help
--externalSpecifies that --query shall search remotely instead of in the local keybox.
--querySpecifies that Kleopatra shall start with the given query string instead of listing the complete local keybox.
--import-certificateSpecifies a file or URL from which to import certificates (or secret keys) from.
This is the command line equivalent of ->.
Would you like to make a comment or contribute an update to this page?
Send feedback to the KDE Docs Team
Kleopatra's configure dialogue can be accessed via ->.
Each of its pages is described in the sections below.
On this page, you can configure which LDAP servers to use for certificate searches. You can also configure their order, as well as some selected LDAP-related settings from the dynamic backend configuration dialogue, available via ->.
To add a new server, click on the Add Service... button. In the dialogue that appears, you can set the Server name, the Port (preset to the default LDAP port), the Base DN (sometimes referred to as the search root or search base), and the usual User name and Password, both of which are only needed if the server requires authentication. Clicking OK adds the server details to the list of servers, while Cancel dismisses the input.
To remove a server from the search list, select it in the list, then press the Remove Service button.
To change the relative search order of servers, select one of them and move it up or down with the arrow buttons right next to the list.
To set the LDAP timeout, i.e. the maximum time the backend will wait for a server to respond, simply use the corresponding input field labelled LDAP timeout.
If one of your servers has a large database, so that even reasonable searches like Smith hit the maximum number of items returned by query, you might want to increase this limit. You can find out easily if you hit the limit during a search, since a dialogue box will pop up in that case, telling you that the results have been truncated.
Some servers may impose their own limits on the number of items returned from a query. In this case, increasing the limit here will not result in more returned items.
Kleopatra allows you to customise the appearance of (validated) keys in the list view. This includes the foreground (text) and background colours, as well as the font.
Each Key Category on the left is assigned a set of colours and a font in which keys belonging to that category are displayed. The category list also acts as a preview of the settings. Categories can be freely defined by the administrator or the power user, see the section called “Creating and Editing Key Categories ” in Chapter 6, Administrator's Guide.
To change the text (foreground) colour of a category, select it in the list, and press the Set Text Colour... button. The standard KDE colour selection dialogue will appear where you can select or create a new colour.
Changing the background colour is done in the same way, just press Set Background Colour... instead.
To change the font, you basically have two options:
Modify the standard font, used for all list views in KDE
Use a custom font.
The first option has the advantage that the font will follow whichever style you choose KDE-wide, whereas the latter gives you full control over the font to use. The choice is yours.
To use the modified standard font, select the category in the list, and tick or un-tick the font modifiers Italic, Bold, and/or Strikeout. You can immediately see the effect on the font in the category list.
To use a custom font, press the Set Font... button. The standard KDE font selection dialogue will appear where you can select the new font. Note that you can still use the font modifiers to change the custom font, just as for modifying the standard font.
To switch back to the standard font, you need to press the Default Appearance button.
Would you like to make a comment or contribute an update to this page?
Send feedback to the KDE Docs Team
Although DNs are hierarchical, the order of the individual components (called relative DNs (RDNs), or DN attributes) is not defined. The order in which the attributes are shown is thus a matter of personal taste or company policy, which is why it is configurable in Kleopatra.
This setting does not only apply to Kleopatra, but to all applications using Kleopatra Technology. At the time of this writing, these include KMail, KAddressBook, as well as Kleopatra itself, of course.
This configuration page basically consists of two lists, one for the known attributes (Available attributes), and one describing the Current attribute order.
Both lists contain entries described by the short from of the attribute (e.g. CN) as well as the spelled-out form (Common Name).
The Available attributes list is always sorted alphabetically, while the Current attribute order list's order reflects the configured DN attribute order: the first attribute in the list is also the one displayed first.
Only attributes explicitly listed in the Current attribute order list are displayed at all. The rest is hidden by default.
However, if the placeholder entry _X_ (All others) is in the “current” list, all unlisted attributes (whether known or not), are inserted at the point of _X_, in their original relative order.
A small example will help to make this more clear:
Given the DN
O=KDE, C=US, CN=Dave Devel, X-BAR=foo, OU=Kleopatra, X-FOO=bar,
the default attribute order of “CN, L, _X_, OU, O, C” will produce the following formatted DN:
CN=Dave Devel, X-BAR=foo, X-FOO=bar, OU=Kleopatra, O=KDE, C=US
while “CN, L, OU, O, C” will produce
CN=Dave Devel, OU=Kleopatra, O=KDE, C=US
To add an attribute to the display order list, select it in the Available attributes list, and press the Add to current attribute order button.
To remove an attribute from the display order list, select it in the Current attribute order list, and press the Remove from current attribute order button.
To move an attribute to the beginning (end), select it in the Current attribute order list, and press the Move to top (Move to bottom) button.
To move an attribute up (down) one slot only, select it in the Current attribute order list, and press the Move one up (Move one down) button.
Would you like to make a comment or contribute an update to this page?
Send feedback to the KDE Docs Team
Would you like to make a comment or contribute an update to this page?
Send feedback to the KDE Docs Team
This Administrator's Guide describes ways to customise Kleopatra that are not accessible via the GUI, but only via config files.
It is assumed that the reader is familiar with the technology used for KDE application configuration, including layout, filesystem location and cascading of KDE config files, as well as the KIOSK framework.
Kleopatra allows you to customise the fields that the user is allowed to enter in order to create their certificate.
Create a group called CertificateCreationWizard in the system-wide kleopatrarc. If you want a custom order of attributes or if you only want certain items to appear, create a key called DNAttributeOrder. The argument is one or more of CN,SN,GN,L,T,OU,O,PC,C,SP,DC,BC,EMAIL If you want to initialise fields with a certain value, write something like Attribute=value. If you want the attribute to be treated as a required one, append an exclamation mark (e.g. CN!,L,OU,O!,C!,EMAIL!, which happens to be the default configuration).
Using the KIOSK mode modifier $e allows to retrieve the values from environment variables or from an evaluated script or binary. If you want to disallow editing of the respective field in addition, use the modifier $i. If you want to disallow the use button, set ShowSetWhoAmI to false.
Due to the nature of the KDE KIOSK framework, using the immutable flag ($i) makes it impossible for the user to override the flag. This is intended behaviour. $i and $e can be used with all other config keys in KDE applications as well.
The following example outlines possible customisations:
[CertificateCreationWizard] ;Disallow to copy personal data from the addressbook, do not allow local override ShowSetWhoAmI[$i]=false ;sets the user name to $USER CN[$e]=$USER ;sets the company name to "My Company", disallows editing O[$i]=My Company ;sets the department name to a value returned by a script OU[$ei]=$(lookup_dept_from_ip) ; sets country to DE, but allows for changes by the user C=DE
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 #, where nn is a number, starting from 0.
The only mandatory key in a Key Filter # group is nName, containing the name of the category as displayed in the config dialogue.
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 dialogue), 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 colour to use. If missing, defaults to whichever background colour is defined globally for list views. |
foreground-color | color | The foreground colour to use. If missing, defaults to whichever foreground colour 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 centred 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. |
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). |
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 (see -> (Shift+F5)). |
| 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 values) are present in a single group, the behaviour is undefined. |
| validity | Analogous to |
[a] Validity is an (ordered) enumeration with the following allowed values: | ||
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=trueTo 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=marginalWould you like to make a comment or contribute an update to this page?
Send feedback to the KDE Docs Team
Would you like to make a comment or contribute an update to this page?
Send feedback to the KDE Docs Team
Kleopatra copyright 2002 Steffen Hansen, Matthias Kalle Dalheimer and Jesper Pedersen., copyright 2004 Daniel Molkentin, copyright 2004 Klarälvdalens Datakonsult AB
Documentation copyright 2002 Steffen Hansen, copyright 2004 Daniel Molkentin, copyright 2004 Klarälvdalens Datakonsult AB
Contributors
Marc Mutz (mutz AT kde.org)
David Faure (faure AT kde.org)
Steffen Hansen (hansen AT kde.org)
Matthias Kalle Dalheimer (kalle AT kde.org)
Jesper Pedersen (blackie AT kde.org)
Daniel Molkentin (molkentin AT kde.org)
This program is licensed under the terms of the GNU General Public License.
This documentation is licensed under the terms of the GNU Free Documentation License.
Would you like to make a comment or contribute an update to this page?
Send feedback to the KDE Docs Team
Would you like to make a comment or contribute an update to this page?
Send feedback to the KDE Docs Team
Would you like to make a comment or contribute an update to this page?
Send feedback to the KDE Docs Team