<?xml version="1.0" ?> <!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ <!ENTITY kleopatra "<application>Kleopatra</application>"> <!ENTITY kwatchgnupg "<application>KWatchGnuPG</application>"> <!ENTITY gpgsm "<application>GpgSM</application>"> <!ENTITY gpg "<application>GPG</application>"> <!ENTITY gpgconf "<application>GpgConf</application>"> <!ENTITY kappname "&kleopatra;"> <!ENTITY package "kdepim"> <!ENTITY smime "<acronym>S/MIME</acronym>"> <!ENTITY % addindex "IGNORE"> <!ENTITY % English "INCLUDE"> <!ENTITY dn "<acronym>DN</acronym>"> <!ENTITY ca "<acronym>CA</acronym>"> ]> <book lang="&language;"> <bookinfo> <title>The &kleopatra; Handbook</title> <authorgroup> <author> <firstname>Marc</firstname> <surname>Mutz</surname> <affiliation> <address><email>marc@kdab.net</email></address> </affiliation> </author> <othercredit role="developer"> <firstname>David</firstname> <surname>Faure</surname> <contrib>Developer</contrib> </othercredit> <othercredit role="developer"> <firstname>Steffen</firstname> <surname>Hansen</surname> <affiliation> <address>&Steffen.Hansen.mail;</address> </affiliation> <contrib>Developer</contrib> </othercredit> <othercredit role="developer"> <firstname>Matthias Kalle</firstname> <surname>Dalheimer</surname> <contrib>Developer</contrib> </othercredit> <othercredit role="developer"> <firstname>Jesper</firstname> <surname>Pedersen</surname> <affiliation> <address>&Jesper.Pedersen.mail;</address> </affiliation> <contrib>Developer</contrib> </othercredit> <othercredit role="developer"> <firstname>Daniel</firstname> <surname>Molkentin</surname> <affiliation> <address>&Daniel.Molkentin.mail;</address> </affiliation> <contrib>Developer</contrib> </othercredit> <!-- TRANS:ROLES_OF_TRANSLATORS --> </authorgroup> <legalnotice>&GPLNotice;</legalnotice> <date>2009-02-19</date> <releaseinfo>2.0.5</releaseinfo> <abstract> <para> &kleopatra; is a tool for managing X.509 and OpenPGP certificates. </para> </abstract> <keywordset> <keyword>KDE</keyword> <keyword>Kapp</keyword> <keyword>X509</keyword> <keyword>LDAP</keyword> <keyword>gpg</keyword> <keyword>gpgsm</keyword> </keywordset> </bookinfo> <chapter id="introduction"> <title>Introduction</title> <para>&kleopatra; is the &kde; tool for managing X.509 and OpenPGP certificates in the &gpgsm; keybox and for retrieving certificates from <acronym>LDAP</acronym> servers.</para> <para>&kleopatra; can be started from &kmail;'s <menuchoice><guimenu>Tools</guimenu> <guimenuitem>Certificate Manager</guimenuitem></menuchoice> menu, as well as from the command line. The &kleopatra; executable is named <userinput><command>kleopatra</command></userinput>.</para> <note><para>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.</para> <para>The name was chosen since this program originates from the <ulink url="http://www.gnupg.org/aegypten2/">Ägypten Projects</ulink> (Ägypten is German for Egypt). &kleopatra; is the German spelling of Cleopatra.</para></note> </chapter> <chapter id="functions"><title>Main Functions</title> <sect1 id="functions-view"><title>Viewing the Local Keybox</title> <!-- Viewing and Refreshing, also Validation --> <para>&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.</para> <para>The main window is divided into the large key listing area consisting of several tabs, the menubar and the <link linkend="functions-search">search bar</link> on top, and a status bar at the bottom.</para> <para>Each line in the key list corresponds to one certificate, identified by the so-called <guilabel>Subject &dn;</guilabel>. &dn; is an acronym for <quote>Distinguished Name</quote>, a hierarchical identifier, much like a file system path with an unusual syntax, that is supposed to globally uniquely identify a given certificate.</para> <para>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 <quote>certificate</quote> and <quote>(public) key</quote> are used interchangeably, and we will not distinguish between them in this manual either, except when explicitly noted.</para> <para>&ca;s must in turn be signed by other &ca;s 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, ⪚ 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.</para> <para>To see which of the certificates are root certificates, you switch to the hierarchical keylist mode with <link linkend="view-hierarchical-key-list"><menuchoice><guimenu>View</guimenu> <guimenuitem>Hierarchical Certificate List</guimenuitem></menuchoice></link>.</para> <para>You can see the details of any certificate by double-clicking it or using <link linkend="view-certificate-details"><menuchoice><guimenu>View</guimenu> <guimenuitem>Certificate Details</guimenuitem></menuchoice></link>. This opens a dialog that shows the most common properties of the certificate, its certificate chain (&ie; the chain of issuers up to the root-&ca;), and a dump of all information the backend is able to extract from the certificate.</para> <para>If you change the keybox without using &kleopatra; (⪚ using &gpgsm;'s command line interface), you can refresh the view with <link linkend="view-redisplay"><menuchoice><shortcut><keycombo action="simul"> <keycap>F5</keycap></keycombo></shortcut><guimenu>View</guimenu> <guimenuitem>Redisplay</guimenuitem></menuchoice></link>.</para> <!-- no longer in kde 4 para>Since validating a key may take some time (⪚ CRLs might need to be fetched), the normal keylisting does not attempt to check the validity of keys. For this, <link linkend="certificates-validate"> <menuchoice><shortcut><keycombo action="simul">&Shift;<keycap>F5</keycap></keycombo> </shortcut><guimenu>Certificates</guimenu><guimenuitem>Validate</guimenuitem></menuchoice></link>, a special variant of <link linkend="view-redisplay"><menuchoice><shortcut><keycombo action="simul"> <keycap>F5</keycap></keycombo></shortcut><guimenu>View</guimenu> <guimenuitem>Redisplay</guimenuitem></menuchoice></link>, is provided. It either checks the selected certificates, or all keys if none are selected.</para--> </sect1> <sect1 id="functions-search"><title>Searching and Importing Certificates</title> <para>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 folder (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.</para> <para>To search for a certificate in an LDAP directory, select <menuchoice><guimenu>File</guimenu><guimenuitem>Lookup Certificates on Server</guimenuitem></menuchoice> and enter some text (⪚ the name of the person you want the certificate for) into the line edit of the <guilabel>Keyserver Certificate Lookup</guilabel> dialog, then click on the <guilabel>Search</guilabel> button. The results will be displayed in the key list below the search bar, where you can select certificates to look at them by clicking the <guibutton>Details</guibutton> button or download them with <guibutton>Import</guibutton> into the local keybox.</para> <!-- Note that you can also download the certificate from the details dialog, using the <guilabel>Import to Local</guilabel> button.</para> not found in 4.2 --> <para>You can configure the list of LDAP servers to search in the <link linkend="configuration-directory-services"><guilabel>Directory Services</guilabel></link> page of &kleopatra;'s configure dialog.</para> <para>If you received the certificate as a file, try <link linkend="file-import-certificates"><menuchoice><guimenu>File</guimenu> <guimenuitem>Import Certificates...</guimenuitem></menuchoice></link>. &gpgsm; needs to understand the format of the certificate file; please refer to &gpgsm;'s manual for a list of supported file formats.</para> <para>If you did not <link linkend="functions-newkey">create your keypair with &gpgsm;</link>, 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 <link linkend="commandline-option-import-certificate"><userinput><command>kleopatra <option>--import-certificate</option> <filename>filename</filename></command></userinput></link> or from within &kleopatra; with <link linkend="file-import-certificates"><menuchoice><guimenu>File</guimenu> <guimenuitem>Import Certificates...</guimenuitem></menuchoice></link>, just as you would to for <quote>normal</quote> certificates.</para> </sect1> <sect1 id="functions-newkey"><title>Creating New Key Pairs</title> <para>The menu item <link linkend="file-new-key-pair"><menuchoice> <guimenu>File</guimenu><guimenuitem>New Certificate...</guimenuitem></menuchoice></link> starts the <guilabel>Certificate Creation Wizard</guilabel> which will guide you through a number of steps to create a certificate request.</para> <para>Whenever you are done with a step in the wizard, press <guibutton>Next</guibutton> to go to the next step (or <guibutton>Back</guibutton> to review steps that are already completed). The certificate request creation can be canceled at any time by pressing the <guibutton>Cancel</guibutton> button. </para> <para>On the first page of the wizard choose which type of certificate you want to create:</para> <variablelist> <varlistentry> <term><guilabel>Create a personal OpenPGP key pair</guilabel></term> <listitem><para>OpenPGP key pairs are created locally, and certified by your friends and acquaintances. There is no central certification authority; instead, every individual creates a personal Web Of Trust by certifying other user's key pairs with his own certificate.</para> <para>You have to enter a <guilabel>Name</guilabel>, <guilabel>EMail</guilabel> and optional a <guilabel>Comment</guilabel>.</para> </listitem> </varlistentry> <varlistentry> <term><guilabel>Create a personal X.509 key pair and certification request</guilabel></term> <listitem> <para>X.509 key pairs are created locally, but certified centrally by a certification authority (&ca;). CAs can certify other CAs, creating a central, hierarchical chain of trust.</para> <para>The next step in the wizard is to type in your personal data for the certificate. The fields to fill out are: <itemizedlist> <listitem> <para><guilabel>Common Name (CN): </guilabel>Your name;</para> </listitem> <listitem> <para><guilabel>Email address (EMAIL): </guilabel>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.</para> </listitem> <listitem> <para><guilabel>Location (L): </guilabel>The town or city in which you live;</para> </listitem> <listitem> <para><guilabel>Organizational unit (OU): </guilabel>The organizational unit you are in (for example, "Logistics");</para> </listitem> <listitem> <para><guilabel>Organization (O): </guilabel>The organization you represent (for example, the company you work for);</para> </listitem> <listitem> <para><guilabel>Country code (C): </guilabel>The two letter code for the country in which you are living (for example, "US");</para> </listitem> </itemizedlist> </para><para> 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. </para> </listitem> </varlistentry> </variablelist> </sect1> <sect1 id="functions-keybox-management"><title>Keybox Management</title> <para>In addition to <link linkend="functions-view">list and validate</link>, <link linkend="functions-search">search and import</link> certificates and <link linkend="functions-newkey">creating new ones</link>, &kleopatra; also has some less often used functions that help you manage your local keybox.</para> <para>These functions include deleting certificates from the local keybox with <link linkend="certificates-delete"><menuchoice><shortcut> <keycombo action="simul"><keycap>Del</keycap></keycombo></shortcut> <guimenu>Certificates</guimenu><guimenuitem>Delete</guimenuitem></menuchoice></link>, as well as manual handling of CRLs (<link linkend="certificates-refresh-crls"> <menuchoice><guimenu>Tools</guimenu><guimenuitem>Refresh Certificates</guimenuitem> <!--???--> </menuchoice></link>, <link linkend="crls-clear-crl-cache"><menuchoice><guimenu>Tools</guimenu> <guimenuitem>Clear CRL Cache</guimenuitem></menuchoice></link>, <link linkend="crls-dump-crl-cache"><menuchoice><guimenu>Tools</guimenu> <guimenuitem>Dump CRL Cache</guimenuitem></menuchoice></link>).</para> </sect1> </chapter> <chapter id="menu"><title>Menu Reference</title> <sect1 id="menufile"><title><guimenu>File</guimenu> Menu</title> <variablelist> <varlistentry id="file-new-key-pair"> <term><menuchoice><shortcut><keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo></shortcut> <guimenu>File</guimenu><guimenuitem>New Certificate...</guimenuitem></menuchoice></term> <listitem> <para><action>Creates a new key pair (public and private)</action> 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.</para> <para>This mode of operation is called <quote>decentralized key generation</quote>, since all keys are created locally. &kleopatra; (and &gpgsm;) do not support <quote>centralized key generation</quote> directly, but you can import the public/secret key bundle that you receive from the &ca; in PKCS#12 format via <menuchoice><guimenu>File</guimenu> <guimenuitem>Import Certificates...</guimenuitem></menuchoice>.</para> </listitem> </varlistentry> <!-- missing menu item <varlistentry> <term><menuchoice><shortcut><keycombo action="simul">&Ctrl;&Shift;<keycap>I</keycap></keycombo></shortcut> <guimenu>File</guimenu><guimenuitem>Lookup Certificates on Server</guimenuitem></menuchoice></term> <listitem> <para>???</para> </listitem> </varlistentry> --> <varlistentry id="file-import-certificates"> <term><menuchoice><shortcut><keycombo action="simul">&Ctrl;<keycap>I</keycap></keycombo></shortcut> <guimenu>File</guimenu><guimenuitem>Import Certificates...</guimenuitem></menuchoice></term> <listitem> <para><action>Imports certificates and/or secret keys from files into the local keybox.</action></para> <para>The format of the certificate file must be supported by &gpgsm;. Please refer to the &gpgsm; manual for a list of supported formats.</para> </listitem> </varlistentry> <varlistentry id="file-export-certificates"> <term><menuchoice><shortcut><keycombo action="simul">&Ctrl;<keycap>E</keycap></keycombo></shortcut> <guimenu>File</guimenu><guimenuitem>Export Certificates...</guimenuitem></menuchoice></term> <listitem> <para><action>Exports the selected certificates</action> into a file.</para> <note><para>This exports only the public keys, even if the secret key is available. Use <menuchoice><guimenu>File</guimenu><guimenuitem>Export Secret Key...</guimenuitem></menuchoice> to export both public and secret keys into a file, but note that this is almost always a bad idea.</para></note> </listitem> </varlistentry> <varlistentry id="file-export-secret-key"> <term><menuchoice><guimenu>File</guimenu><guimenuitem>Export Secret Key...</guimenuitem></menuchoice></term> <listitem> <para><action>Exports both the public and the secret key to a (PKCS#12) file.</action></para> <warning><para>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.</para></warning> </listitem> </varlistentry> <!--missing menu items <varlistentry> <term><menuchoice><shortcut><keycombo action="simul">&Ctrl;&Shift;<keycap>E</keycap></keycombo></shortcut> <guimenu>File</guimenu><guimenuitem>Export Certificates to Server...</guimenuitem></menuchoice></term> <listitem> <para>???</para> </listitem> </varlistentry> <varlistentry> <term><menuchoice> <guimenu>File</guimenu><guimenuitem>Decrypt/Verify Files...</guimenuitem></menuchoice></term> <listitem> <para>???</para> </listitem> </varlistentry> <varlistentry> <term><menuchoice> <guimenu>File</guimenu><guimenuitem>Sign/Encrypt Files...</guimenuitem></menuchoice></term> <listitem> <para>???</para> </listitem> </varlistentry> <varlistentry> <term><menuchoice><shortcut><keycombo action="simul">&Ctrl;<keycap>W</keycap></keycombo></shortcut> <guimenu>File</guimenu><guimenuitem>Close...</guimenuitem></menuchoice></term> <listitem> <para>???</para> </listitem> </varlistentry> --> <!--not in 4.2 <varlistentry id="file-import-crls"> <term><menuchoice><guimenu>File</guimenu><guimenuitem>Import CRLs...</guimenuitem></menuchoice></term> <listitem> <para><action>Lets you manually import CRLs from files.</action></para> <para>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.</para> <note><para>For CRL import to work, the <application>dirmngr</application> tool must be in the search <varname>PATH</varname>. If this menu item is disabled, you should contact the system administrator and ask them to install <application>dirmngr</application>.</para></note> <para>You can view the contents of the local CRL cache from the menu item <menuchoice><guimenu>CRLs</guimenu><guimenuitem>Dump CRL Cache</guimenuitem> </menuchoice>. This will display a dialog with information about the CRLs in the cache and the fingerprints of the certificates in each CRL. </para> </listitem> </varlistentry> --> <varlistentry id="file-quit"> <term><menuchoice><shortcut><keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo></shortcut> <guimenu>File</guimenu><guimenuitem>Quit</guimenuitem></menuchoice></term> <listitem> <para><action>Terminates &kleopatra;.</action></para> </listitem> </varlistentry> </variablelist> </sect1> <!-- File Menu --> <sect1 id="menuview"><title><guimenu>View</guimenu> Menu</title> <variablelist> <varlistentry id="view-redisplay"> <term><menuchoice><shortcut><keycombo action="simul"><keycap>F5</keycap></keycombo> </shortcut><guimenu>View</guimenu><guimenuitem>Redisplay</guimenuitem></menuchoice></term> <listitem> <para><action>Redisplays the selected certificates or refreshes the certificate list.</action></para> <para>If there are selected certificates, the refresh operation is restricted to those selected entries.</para> <para>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.</para> <para>If no query has been performed, the whole keybox contents is re-fetched and re-displayed.</para> <para>You can use this if you have changed the contents of the keybox by other means than &kleopatra; (⪚ by using &gpgsm;'s command line interface).</para> </listitem> </varlistentry> <varlistentry id="view-stop-operation"> <term><menuchoice><shortcut><keycombo action="simul"><keycap>Esc</keycap></keycombo></shortcut> <guimenu>View</guimenu><guimenuitem>Stop Operation</guimenuitem></menuchoice></term> <listitem> <para><action>Stops (cancels) all pending operations,</action> ⪚ a search or a download.</para> <note><para>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 behavior.</para></note> </listitem> </varlistentry> <varlistentry id="view-certificate-details"> <term><menuchoice><guimenu>View</guimenu><guimenuitem>Certificate Details</guimenuitem></menuchoice></term> <listitem> <para><action>Shows the details of the currently selected certificate.</action></para> <para>This function is also available by double-clicking the corresponding item in the list view directly.</para> <!--FIXME: link to the dialog's help, but where do we put _that_?--> </listitem> </varlistentry> <varlistentry id="view-hierarchical-key-list"> <term><menuchoice><guimenu>View</guimenu><guimenuitem>Hierarchical Certificate List</guimenuitem></menuchoice></term> <listitem> <para><action> Toggles between hierarchical and flat keylist mode. </action></para> <para>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 <link linkend="functions-search">search bar</link>).</para> <para>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.</para> </listitem> </varlistentry> <varlistentry id="view-expand-all"> <term><menuchoice><shortcut><keycombo action="simul">&Ctrl;<keycap>.</keycap> </keycombo></shortcut><guimenu>View</guimenu><guimenuitem>Expand All</guimenuitem></menuchoice></term> <listitem> <para>(This function is only available when <link linkend="view-hierarchical-key-list"><menuchoice><guimenu>View</guimenu> <guimenuitem>Hierarchical Certificate List</guimenuitem></menuchoice></link> is on.)</para> <para><action>Expands all list items in the certificate list view,</action> &ie; makes all items visible.</para> <para>This is the default when entering hierarchical keylist mode.</para> <para>You can still expand and collapse each individual item by itself, of course.</para> </listitem> </varlistentry> <varlistentry id="view-collapse-all"> <term><menuchoice><shortcut><keycombo action="simul">&Ctrl;<keycap>,</keycap> </keycombo></shortcut><guimenu>View</guimenu><guimenuitem>Collapse All</guimenuitem></menuchoice></term> <listitem> <para>(This function is only available when <link linkend="view-hierarchical-key-list"><menuchoice><guimenu>View</guimenu> <guimenuitem>Hierarchical Certificate List</guimenuitem></menuchoice></link> is on.)</para> <para><action>Collapses all list items in the certificate list view,</action> &ie; hides all but the top-level items.</para> <para>You can still expand and collapse each individual item by itself, of course.</para> </listitem> </varlistentry> </variablelist> </sect1> <sect1 id="menucertificates"><title><guimenu>Certificates</guimenu> Menu</title> <variablelist> <!-- missing menu item <varlistentry id="certificates-certify"> <term><menuchoice> <guimenu>Certificates</guimenu><guimenuitem>Certify Certificate...</guimenuitem></menuchoice></term> <listitem> <para><action>???</action></para> no longer in kde4 <para>This is similar to <link linkend="view-redisplay"><menuchoice><shortcut><keycombo action="simul"> <keycap>F5</keycap></keycombo></shortcut><guimenu>View</guimenu> <guimenuitem>Redisplay</guimenuitem></menuchoice></link>, 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 color and font preferences set in the <link linkend="configuration-appearance"><guilabel>Appearance</guilabel> page</link> of &kleopatra;'s <link linkend="configuration">configure dialog</link>.</para> <warning><para>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 (⪚ for signing, signature verification, encryption or decryption).</para></warning> </listitem> </varlistentry> --> <!--not in 4.2 varlistentry id="certificates-refresh-crls"> <term><menuchoice><guimenu>Certificates</guimenu><guimenuitem>Refresh CRLs</guimenuitem></menuchoice></term> <listitem> <para><action>Fetches the current CRLs for all selected keys,</action> even though they would normally not be fetched when using the key.</para> <para>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.</para> <para>You may use this ⪚ if you have sideband knowledge that a key has been revoked, and you want the backend to reflect this <emphasis>now</emphasis> instead of relying on this to automatically happen at the next scheduled CRL update.</para> <warning><para>Excessive use of this function might put a high load on your provider's or company's network, since CRLs of large organizations can be surprisingly big (several megabytes are not uncommon).</para> <para>Use this function scarcely.</para></warning> </listitem> </varlistentry--> <!-- missing menu items <varlistentry> <term><menuchoice> <guimenu>Certificates</guimenu><guimenuitem>Change Ownertrust...</guimenuitem></menuchoice></term> <listitem> <para>???</para> </listitem> </varlistentry> <varlistentry> <term><menuchoice> <guimenu>Certificates</guimenu><guimenuitem>Expire Date...</guimenuitem></menuchoice></term> <listitem> <para>???</para> </listitem> </varlistentry> <varlistentry> <term><menuchoice> <guimenu>Certificates</guimenu><guimenuitem>Change Passphrase...</guimenuitem></menuchoice></term> <listitem> <para>???</para> </listitem> </varlistentry> <varlistentry> <term><menuchoice> <guimenu>Certificates</guimenu><guimenuitem>Add User-ID...</guimenuitem></menuchoice></term> <listitem> <para>???</para> </listitem> </varlistentry> --> <varlistentry id="certificates-delete"> <term><menuchoice><shortcut><keycombo action="simul"><keycap>Del</keycap></keycombo></shortcut> <guimenu>Certificates</guimenu><guimenuitem>Delete</guimenuitem></menuchoice></term> <listitem> <para><action>Deletes selected certificate(s)</action> from the local keyring.</para> <para>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 <link linkend="functions-search">search bar</link> or the <link linkend="view-hierarchical-key-list"><menuchoice><guimenu>View</guimenu> <guimenuitem>Hierarchical Key List</guimenuitem></menuchoice></link> function to regain control over the lot of certificates.</para> </listitem> </varlistentry> <varlistentry> <term><menuchoice><guimenu>Certificates</guimenu><guimenuitem>Dump Certificate</guimenuitem></menuchoice></term> <listitem> <para>Shows the detailed contents of the &gpgsm; CRL cache.</para> </listitem> </varlistentry> <!--not in 4.2 varlistentry id="certificates-download"> <term><menuchoice><guimenu>Certificates</guimenu><guimenuitem>Download</guimenuitem></menuchoice></term> <listitem> <para><action>Downloads the selected certificate(s) from the LDAP to the local keybox.</action></para> </listitem> </varlistentry--> </variablelist> </sect1> <sect1 id="menutools"><title><guimenu>Tools</guimenu> Menu</title> <variablelist> <varlistentry id="tools-gnupg-log-viewer"> <term><menuchoice><guimenu>Tools</guimenu><guimenuitem>GnuPG Log Viewer...</guimenuitem></menuchoice></term> <listitem> <para><action>Starts <ulink url="help:/kwatchgnupg/index.html">&kwatchgnupg;</ulink></action>, a tool to present the debug output of GnuPG application. If signing, encryption, or verification mysteriously stop working, you might find out why by looking at the log.</para> </listitem> </varlistentry> <varlistentry id="certificates-refresh-crls"> <term><menuchoice><guimenu>Tools</guimenu><guimenuitem>Refresh X.509 or OpenPGP Certificates</guimenuitem></menuchoice></term> <listitem> <para>Refreshing X.509 or OpenPGP certificates implies downloading all certificates and CRLs, to check if any of them have been revoked in the meantime.</para> <para>This can put a severe strain on your own as well as other people's network connections, and can take up to an hour or more to complete, depending on your network connection, and the number of certificates to check.</para> </listitem> </varlistentry> <varlistentry id="crls-clear-crl-cache"> <term><menuchoice><guimenu>Tools</guimenu><guimenuitem>Clear CRL Cache</guimenuitem></menuchoice></term> <listitem> <para><action>Clears the &gpgsm; CRL cache.</action></para> <para>You probably never need this. You can force a refresh of the CRL cache by selecting all certificates and using <link linkend="certificates-refresh-crls"><menuchoice> <guimenu>Tools</guimenu><guimenuitem>Refresh Certificates</guimenuitem></menuchoice></link> instead.</para> </listitem> </varlistentry> <varlistentry id="crls-dump-crl-cache"> <term><menuchoice><guimenu>Tools</guimenu><guimenuitem>Dump CRL Cache</guimenuitem></menuchoice></term> <listitem> <para><action>Shows the detailed contents of the &gpgsm; CRL cache.</action></para> </listitem> </varlistentry> <varlistentry id="settings-configure-gpgme-backend"> <term><menuchoice><guimenu>Tools</guimenu><guimenuitem>Configure GnuPG Backend...</guimenuitem></menuchoice></term> <listitem> <para><action>Opens a dialog that allows you to configure every aspect of &gpgsm; and other backend modules.</action></para> <para>This dialog is dynamically built from the output of the &gpgconf; utility and may thus change when backend modules are updated.</para> </listitem> </varlistentry> </variablelist> </sect1> <sect1 id="menusettings"><title><guimenu>Settings</guimenu> Menu</title> <variablelist> <!-- missing items <varlistentry> <term><menuchoice> <guimenu>Settings</guimenu><guimenuitem>Perform Selftest</guimenuitem></menuchoice></term> <listitem> <para>???</para> </listitem> </varlistentry> <varlistentry> <term><menuchoice> <guimenu>Settings</guimenu><guisubmenu>Toolbars</guisubmenu></menuchoice></term> <listitem> <para>???</para> </listitem> </varlistentry> --> <varlistentry id="settings-show-statusbar"> <term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Show Statusbar</guimenuitem></menuchoice></term> <listitem> <para><action>Toggles the visibility of the bottom status bar.</action></para> </listitem> </varlistentry> <!-- missing item <varlistentry> <term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Toolbars...</guimenuitem></menuchoice></term> <listitem> <para>???</para> </listitem> </varlistentry> --> <varlistentry id="settings-configure-shortcuts"> <term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Shortcuts...</guimenuitem></menuchoice></term> <listitem> <para><action>Opens the standard &kde; shortcut configuration dialog, where you can assign and re-assign keyboard shortcuts for all menu items.</action></para> </listitem> </varlistentry> <varlistentry id="settings-configure-kleopatra"> <term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &kleopatra;...</guimenuitem></menuchoice></term> <listitem> <para><action>Opens &kleopatra;'s configure dialog.</action></para> <para>See <xref linkend="configuration"/> for more details.</para> </listitem> </varlistentry> </variablelist> </sect1> <sect1 id="menuwindow"><title><guimenu>Window</guimenu> Menu</title> <para>The <guimenu>Window</guimenu> menu allows you to manage the tabs. Using the items in this menu you can rename a tab, add a new tab, duplicate the current tab, close the current tab, and move the current tab to the left or right.</para> <para>By clicking with the &RMB; click on a tab you open a context menu, where you can also select the same actions.</para> </sect1> <sect1 id="menuhelp"><title><guimenu>Help</guimenu> Menu</title> <para>The <guimenu>Help</guimenu> menu contains the standard &kde; help menu.</para> &help.menu.documentation; </sect1> </chapter> <chapter id="commandline-options"><title>Command Line Options Reference</title> <para>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 <userinput><command>kleopatra <option>--help</option></command></userinput>.</para> <variablelist> <varlistentry> <term><option>--external</option></term> <listitem> <para>Run UI server only, hide main window</para> </listitem> </varlistentry> <varlistentry> <term><option>-p</option> <option>--openpgp</option></term> <listitem> <para>Use OpenPGP for the following operation</para> </listitem> </varlistentry> <varlistentry> <term><option>-c</option> <option>--cms</option></term> <listitem> <para>Use CMS (X.509, S/MIME) for the following operation</para> </listitem> </varlistentry> <varlistentry id="commandline-option-import-certificate"> <term><option>-i</option> <option>--import-certificate</option></term> <listitem> <para><action>Specifies a file or &URL; from which to import certificates (or secret keys) from.</action></para> <para>This is the command line equivalent of <link linkend="file-import-certificates"><menuchoice><guimenu>File</guimenu> <guimenuitem>Import Certificates...</guimenuitem></menuchoice></link>.</para> </listitem> </varlistentry> <varlistentry> <term><option>-e</option> <option>--encrypt</option></term> <listitem> <para>Encrypt file(s)</para> </listitem> </varlistentry> <varlistentry> <term><option>-s</option> <option>--sign</option></term> <listitem> <para>Sign file(s)</para> </listitem> </varlistentry> <varlistentry> <term><option>-E</option> <option>--encrypt-sign</option></term> <listitem> <para>Encrypt and/or sign file(s)</para> </listitem> </varlistentry> <varlistentry> <term><option>-d</option> <option>--decrypt</option></term> <listitem> <para>Decrypt file(s)</para> </listitem> </varlistentry> <varlistentry> <term><option>-V</option> <option>--verify</option></term> <listitem> <para>Verify file/signature</para> </listitem> </varlistentry> <varlistentry> <term><option>-D</option> <option>--decrypt-verify</option></term> <listitem> <para>Decrypt and/or verify file(s)</para> </listitem> </varlistentry> </variablelist> </chapter> <chapter id="configuration"><title>Configuring &kleopatra;</title> <para>&kleopatra;'s configure dialog can be accessed via <link linkend="settings-configure-kleopatra"><menuchoice><guimenu>Settings</guimenu> <guimenuitem>Configure &kleopatra;...</guimenuitem></menuchoice></link>.</para> <para>Each of its pages is described in the sections below.</para> <sect1 id="configuration-directory-services"><title>Configuring <guilabel>Directory Services</guilabel></title> <para>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 dialog, available via <link linkend="settings-configure-gpgme-backend"><menuchoice><guimenu>Tools</guimenu> <guimenuitem>Configure GnuPG Backend...</guimenuitem></menuchoice></link>.</para> <para>To add a new server, click on the <guilabel>New</guilabel> button. Then you can set the <guilabel>Server Name</guilabel>, the <guilabel>Server Port</guilabel> (preset to the default LDAP port), the <guilabel>Base &dn;</guilabel> (sometimes referred to as the search root or search base), and the usual <guilabel>User Name</guilabel> and <guilabel>Password</guilabel>, both of which are only needed if the server requires authentication.</para> <para>To remove a server from the search list, select it in the list, then press the <guilabel>Delete</guilabel> button.</para> <!-- not in 4.2 <para>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.</para> --> <para>To set the LDAP timeout, &ie; the maximum time the backend will wait for a server to respond, simply use the corresponding input field labeled <guilabel>LDAP timeout (minutes:seconds)</guilabel>.</para> <para>If one of your servers has a large database, so that even reasonable searches like <userinput>Smith</userinput> hit the <guilabel>maximum number of items returned by query</guilabel>, you might want to increase this limit. You can find out easily if you hit the limit during a search, since a dialog box will pop up in that case, telling you that the results have been truncated.</para> <note><para>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.</para></note> </sect1> <sect1 id="configuration-appearance"><title>Configuring visual <guilabel>Appearance</guilabel></title> <para>&kleopatra; allows you to customize the appearance of (validated) keys in the list view. This includes the foreground (text) and background colors, as well as the font.</para> <para>Each <guilabel>Key Category</guilabel> on the left is assigned a set of colors 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 <xref linkend="admin-key-filters"/> in <xref linkend="admin"/>.</para> <para>To change the text (foreground) color of a category, select it in the list, and press the <guilabel>Set Text Color...</guilabel> button. The standard &kde; color selection dialog will appear where you can select or create a new color.</para> <para>Changing the background color is done in the same way, just press <guilabel>Set Background Color...</guilabel> instead.</para> <para>To change the font, you basically have two options:</para> <orderedlist> <listitem><para>Modify the standard font, used for all list views in &kde;</para></listitem> <listitem><para>Use a custom font.</para></listitem> </orderedlist> <para>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.</para> <para>To use the modified standard font, select the category in the list, and check or uncheck the font modifiers <guilabel>Italic</guilabel>, <guilabel>Bold</guilabel>, and/or <guilabel>Strikeout</guilabel>. You can immediately see the effect on the font in the category list.</para> <para>To use a custom font, press the <guilabel>Set Font...</guilabel> button. The standard &kde; font selection dialog 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.</para> <para>To switch back to the standard font, you need to press the <guilabel>Default Appearance</guilabel> button.</para> </sect1> <sect1 id="configuration-dn-order"><title>Configuring the <guilabel>&dn; Attribute Order</guilabel></title> <para>Although &dn;s are hierarchical, the order of the individual components (called relative &dn;s (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;.</para> <note><para>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.</para></note> <para>This configuration page basically consists of two lists, one for the known attributes (<guilabel>Available attributes</guilabel>), and one describing the <guilabel>Current attribute order</guilabel>.</para> <para>Both lists contain entries described by the short from of the attribute (⪚ <guilabel>CN</guilabel>) as well as the spelled-out form (<guilabel>Common Name</guilabel>).</para> <para>The <guilabel>Available attributes</guilabel> list is always sorted alphabetically, while the <guilabel>Current attribute order</guilabel> list's order reflects the configured &dn; attribute order: the first attribute in the list is also the one displayed first.</para> <para>Only attributes explicitly listed in the <guilabel>Current attribute order</guilabel> list are displayed at all. The rest is hidden by default.</para> <para>However, if the placeholder entry <guilabel>_X_</guilabel> (<guilabel>All others</guilabel>) is in the <quote>current</quote> list, all unlisted attributes (whether known or not), are inserted at the point of <guilabel>_X_</guilabel>, in their original relative order.</para> <para>A small example will help to make this more clear:</para> <informalexample> <para>Given the &dn;</para> <blockquote> <para> O=&kde;, C=US, CN=Dave Devel, X-BAR=foo, OU=&kleopatra;, X-FOO=bar, </para> </blockquote> <para>the default attribute order of <quote>CN, L, _X_, OU, O, C</quote> will produce the following formatted &dn;:</para> <blockquote> <para> CN=Dave Devel, X-BAR=foo, X-FOO=bar, OU=&kleopatra;, O=&kde;, C=US </para> </blockquote> <para>while <quote>CN, L, OU, O, C</quote> will produce</para> <blockquote> <para> CN=Dave Devel, OU=&kleopatra;, O=&kde;, C=US </para> </blockquote> </informalexample> <para>To add an attribute to the display order list, select it in the <guilabel>Available attributes</guilabel> list, and press the <guilabel>Add to current attribute order</guilabel> button.</para> <para>To remove an attribute from the display order list, select it in the <guilabel>Current attribute order</guilabel> list, and press the <guilabel>Remove from current attribute order</guilabel> button.</para> <para>To move an attribute to the beginning (end), select it in the <guilabel>Current attribute order</guilabel> list, and press the <guilabel>Move to top</guilabel> (<guilabel>Move to bottom</guilabel>) button.</para> <para>To move an attribute up (down) one slot only, select it in the <guilabel>Current attribute order</guilabel> list, and press the <guilabel>Move one up</guilabel> (<guilabel>Move one down</guilabel>) button.</para> </sect1> </chapter> <chapter id="admin"><title>Administrator's Guide</title> <para>This Administrator's Guide describes ways to customize &kleopatra; that are not accessible via the &GUI;, but only via config files.</para> <para>It is assumed that the reader is familiar with the technology used for &kde; application configuration, including layout, file system location and cascading of &kde; config files, as well as the KIOSK framework.</para> <sect1 id="admin-certificate-request-wizard"><title>Customization of the Certificate-Creation Wizard</title> <para>&kleopatra; allows you to customize the fields that the user is allowed to enter in order to create their certificate.</para> <para>Create a group called <literal>CertificateCreationWizard</literal> in the system-wide <filename>kleopatrarc</filename>. If you want a custom order of attributes or if you only want certain items to appear, create a key called <varname>DNAttributeOrder</varname>. The argument is one or more of <varname>CN,SN,GN,L,T,OU,O,PC,C,SP,DC,BC,EMAIL</varname> If you want to initialize 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. <varname>CN!,L,OU,O!,C!,EMAIL!</varname>, which happens to be the default configuration).</para> <para> Using the <acronym>KIOSK</acronym> mode modifier <varname>$e</varname> 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 <varname>$i</varname>. If you want to disallow the use <guibutton>Insert My Address</guibutton> button, set <varname>ShowSetWhoAmI</varname> to false.</para> <tip><para> Due to the nature of the &kde; <acronym>KIOSK</acronym> framework, using the immutable flag (<varname>$i</varname>) makes it impossible for the user to override the flag. This is intended behavior. <varname>$i</varname> and <varname>$e</varname> can be used with all other config keys in &kde; applications as well.</para></tip> <para>The following example outlines possible customizations:</para> <para> <programlisting> [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 </programlisting> </para> </sect1> <sect1 id="admin-key-filters"> <title> Creating and Editing Key Categories </title> <para> &kleopatra; allows the user to configure the <link linkend="configuration-appearance">visual appearance</link> of keys based on a concept called <guilabel>Key Categories</guilabel>. <guilabel>Key Categories</guilabel> are also used to filter the list of certificates. This section describes how you can edit the available categories and add new ones. </para> <para> 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 <filename>libkleopatrarc</filename>. The first one to match defines the category, based on a concept of <emphasis>specificity</emphasis>, explained further below. </para> <para> Each key filter is defined in a config group named <literal>Key Filter #<replaceable>n</replaceable></literal>, where <replaceable>n</replaceable> is a number, starting from <literal>0</literal>. </para> <para> The only mandatory keys in a <literal>Key Filter #<replaceable>n</replaceable></literal> group are <varname>Name</varname>, containing the name of the category as displayed in the <link linkend="configuration-appearance">config dialog</link>, and <varname>id</varname>, which is used as a reference for the filter in other configuration sections (such as <literal>View #<replaceable>n</replaceable></literal>). </para> <para> <xref linkend="table-key-filters-appearance"/> lists all keys that define the display properties of keys belonging to that category (&ie; those keys that can be adjusted in the <link linkend="configuration-appearance">config dialog</link>), whereas <xref linkend="table-key-filters-criteria"/> lists all keys that define the criteria the filter matches keys against. </para> <table id="table-key-filters-appearance"> <title>Key-Filter Configuration Keys Defining Display Properties</title> <tgroup cols="3"> <colspec colnum="2" align="center"/> <thead> <row> <entry>Config Key</entry> <entry>Type</entry> <entry>Description</entry> </row> </thead> <!--tfoot/--> <tbody> <row> <entry><varname>background-color</varname></entry> <entry>color</entry> <entry> The background color to use. If missing, defaults to whichever background color is defined globally for list views. </entry> </row> <row> <entry><varname>foreground-color</varname></entry> <entry>color</entry> <entry> The foreground color to use. If missing, defaults to whichever foreground color is defined globally for list views. </entry> </row> <row> <entry><varname>font</varname></entry> <entry>font</entry> <entry> 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. </entry> </row> <row> <entry><varname>font-bold</varname></entry> <entry>boolean</entry> <entry> If set to <literal>true</literal> and <varname>font</varname> is not set, uses the default list view font with bold font style added (if available). Ignored if <varname>font</varname> is also present. </entry> </row> <row> <entry><varname>font-italic</varname></entry> <entry>boolean</entry> <entry> Analogous to <varname>font-bold</varname>, but for italic font style instead of bold. </entry> </row> <row> <entry><varname>font-strikeout</varname></entry> <entry>boolean</entry> <entry> If <literal>true</literal>, draws a centered line over the font. Applied even if <varname>font</varname> is set. </entry> </row> <row> <entry><varname>icon</varname></entry> <entry>text</entry> <entry> The name of an icon to show in the first column. Not yet implemented. </entry> </row> </tbody> </tgroup> </table> <table id="table-key-filters-criteria"> <title>Key-Filter Configuration Keys Defining Filter Criteria</title> <tgroup cols="3"> <colspec colnum="2" align="center"/> <thead> <row> <entry>Config Key</entry> <entry>Type</entry> <entry>If specified, filter matches when...</entry> </row> </thead> <!--tfoot/--> <tbody> <row> <entry><varname>is-revoked</varname></entry> <entry>boolean</entry> <entry>the key has been revoked.</entry> </row> <row> <entry><varname>match-context</varname></entry> <entry> context<footnote> <para> Context is an enumeration with the following allowed values: <literal>appearance</literal>, <literal>filtering</literal> and <literal>any</literal>. </para> </footnote> </entry> <entry>the context in which this filter matches.</entry> </row> <row> <entry><varname>is-expired</varname></entry> <entry>boolean</entry> <entry>the key is expired.</entry> </row> <row> <entry><varname>is-disabled</varname></entry> <entry>boolean</entry> <entry> the key has been disabled (marked for not using) by the user. Ignored for &smime; keys. </entry> </row> <row> <entry><varname>is-root-certificate</varname></entry> <entry>boolean</entry> <entry> the key is a root certificate. Ignored for OpenPGP keys. </entry> </row> <row> <entry><varname>can-encrypt</varname></entry> <entry>boolean</entry> <entry> the key can be used for encryption. </entry> </row> <row> <entry><varname>can-sign</varname></entry> <entry>boolean</entry> <entry> the key can be used for signing. </entry> </row> <row> <entry><varname>can-certify</varname></entry> <entry>boolean</entry> <entry> the key can be used for signing (certifying) other keys. </entry> </row> <row> <entry><varname>can-authenticate</varname></entry> <entry>boolean</entry> <entry> the key can be used for authentication (⪚ as an <acronym>TLS</acronym> client certificate). </entry> </row> <row> <entry><varname>is-qualified</varname></entry> <entry>boolean</entry> <entry> the key can be used to make Qualified Signatures (as defined by the German Digital Signature Law). </entry> </row> <row> <entry><varname>is-cardkey</varname></entry> <entry>boolean</entry> <entry> the key material is stored on a smartcard (instead of on the computer). </entry> </row> <row> <entry><varname>has-secret-key</varname></entry> <entry>boolean</entry> <entry> the secret key for this key pair is available. </entry> </row> <row> <entry><varname>is-openpgp-key</varname></entry> <entry>boolean</entry> <entry> the key is an OpenPGP key (<literal>true</literal>), or an &smime; key (<literal>false</literal>). </entry> </row> <row> <entry><varname>was-validated</varname></entry> <entry>boolean</entry> <entry> the key has been validated. </entry> </row> <row> <entry><varname><replaceable>prefix</replaceable>-ownertrust</varname></entry> <entry> validity<footnote> <para> Validity is an (ordered) enumeration with the following allowed values: <literal>unknown</literal>, <literal>undefined</literal>, <literal>never</literal>, <literal>marginal</literal>, <literal>full</literal>, <literal>ultimate</literal>. See the &gpg; and &gpgsm; manuals for a detailed explanation. </para> </footnote> </entry> <entry> the key has exactly (<replaceable>prefix</replaceable> = <literal>is</literal>), has anything but (<replaceable>prefix</replaceable> = <literal>is-not</literal>), has at least (<replaceable>prefix</replaceable> = <literal>is-at-least</literal>), or has at most (<replaceable>prefix</replaceable> = <literal>is-at-most</literal>) the ownertrust given as the value of the config key. If more than one <varname><replaceable>prefix</replaceable>-ownertrust</varname> keys (with different <replaceable>prefix</replaceable> values) are present in a single group, the behavior is undefined. </entry> </row> <row> <entry><varname><replaceable>prefix</replaceable>-validity</varname></entry> <entry>validity</entry> <entry> Analogous to <varname><replaceable>prefix</replaceable>-ownertrust</varname>, but for key validity instead of ownertrust. </entry> </row> </tbody> </tgroup> </table> <note> <para> Some of the more interesting criteria, such as <varname>is-revoked</varname> or <varname>is-expired</varname> will only work on <emphasis>validated</emphasis> keys, which is why, by default, only validated keys are checked for revocation and expiration, although you are free to remove these extra checks. </para> </note> <para> In addition to the config keys listed above, a key filter may also have an <varname>id</varname> and <varname>match-contexts</varname>. </para> <para> Using the filter's <varname>id</varname>, which defaults to the filter's config group name if not given or empty, you can reference the key filter elsewhere in the configuration, ⪚ in &kleopatra;'s View configurations<!--TODO write and link-->. The <varname>id</varname> is not interpreted by &kleopatra;, so you can use any string you like, as long as it's unique. </para> <para> The <varname>match-contexts</varname> limits the applicability of the filter. Two contexts are currently defined: The <literal>appearance</literal> context is used when defining coloring and font properties for the views. The <literal>filtering</literal> context is used to selectively include (and exclude) certificate from views. <literal>any</literal> can be used to signify all currently defined contexts, and is the default if <varname>match-contexts</varname> is not given, or otherwise produces no contexts. This ensures that no key filter can end up <quote>dead</quote>, &ie; with no contexts to apply it in. </para> <para> 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 (<literal>!</literal>), indicating negation. The tokens act in order on an internal list of contexts, which starts out empty. This is best explained by an example: <literal>any !appearance</literal> is the same as <literal>filtering</literal>, and <literal>appearance !appearance</literal> is producing the empty set, as is <literal>!any</literal>. However, the last two will be internally replaced by <literal>any</literal>, since they produce no contexts at all. </para> <para> In general, criteria not specified (&ie; 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, &ie; the criteria are AND'ed together. </para> <para> Each filter has an implied <quote>specificity</quote> 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. </para> <example> <title> Examples of key filters </title> <para> To check for all expired, but non-revoked root certificates, you would use a key filter defined as follows: </para> <!-- isn't there a better way to not indent this in the output??? --> <screen><!-- -->[Key Filter #<replaceable>n</replaceable>] Name=expired, but not revoked was-validated=true is-expired=true is-revoked=false is-root-certificate=true ; ( specificity 4 )<!-- --></screen> <para> To check for all disabled OpenPGP keys (not yet supported by &kleopatra;) with ownertrust of at least <quote>marginal</quote>, you would use: </para> <screen><!-- -->[Key Filter #<replaceable>n</replaceable>] Name=disabled OpenPGP keys with marginal or better ownertrust is-openpgp=true is-disabled=true is-at-least-ownertrust=marginal ; ( specificity 3 )<!-- --></screen> </example> </sect1> </chapter> <!-- Administrator's Guide --> <chapter id="credits-and-license"> <title>Credits and License</title> <para>&kleopatra; copyright 2002 &Steffen.Hansen;, &Matthias.Kalle.Dalheimer; and &Jesper.Pedersen;., copyright 2004 &Daniel.Molkentin;, copyright 2004 Klarälvdalens Datakonsult AB</para> <para>Documentation copyright 2002 &Steffen.Hansen;, copyright 2004 &Daniel.Molkentin;, copyright 2004 Klarälvdalens Datakonsult AB</para> <itemizedlist> <title>Contributors</title> <listitem> <para>&Marc.Mutz; &Marc.Mutz.mail;</para> </listitem> <listitem> <para>&David.Faure; &David.Faure.mail;</para> </listitem> <listitem> <para>&Steffen.Hansen; <email>hansen@kde.org</email></para> </listitem> <listitem> <para>&Matthias.Kalle.Dalheimer; &Matthias.Kalle.Dalheimer.mail;</para> </listitem> <listitem> <para>&Jesper.Pedersen; &Jesper.Pedersen.mail;</para> </listitem> <listitem> <para>&Daniel.Molkentin; &Daniel.Molkentin.mail;</para> </listitem> </itemizedlist> <!-- TRANS:CREDIT_FOR_TRANSLATORS --> &underFDL; &underGPL; </chapter> &documentation.index; </book> <!-- Local Variables: mode: sgml sgml-minimize-attributes:nil sgml-general-insert-case:lower sgml-indent-step:0 sgml-indent-data:nil End: // vim:ts=2:sw=2:tw=78:noet -->