<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN" "dtd/kdedbx45.dtd" [
  <!ENTITY kleopatra "<application>Kleopatra</application>">
  <!ENTITY uiserver "UiServer">
  <!ENTITY kwatchgnupg "<application>KWatchGnuPG</application>">
  <!ENTITY gpgsm "<application>GpgSM</application>">
  <!ENTITY gnupg "<application>GnuPG</application>">
  <!ENTITY gpg "<application>GPG</application>">
  <!ENTITY gpgme "<application>GpgME</application>"> <!--### there's no <library>-->
  <!ENTITY gpgconf "<application>GpgConf</application>">
  <!ENTITY gpgagent "<application>GpgAgent</application>">
  <!ENTITY dirmngr "<application>DirMngr</application>">
  <!ENTITY scdaemon "<application>SCDaemon</application>">
  <!ENTITY pinentry "<application>PinEntry</application>">
  <!ENTITY kappname "&kleopatra;">
  <!ENTITY package "kdepim">
  <!ENTITY ldap "<acronym>LDAP</acronym>">
  <!ENTITY ldaps "<acronym>LDAPS</acronym>">
  <!ENTITY http "<acronym>HTTP</acronym>">
  <!ENTITY smime "<acronym>S/MIME</acronym>">
  <!ENTITY openpgp "<acronym>OpenPGP</acronym>">
  <!ENTITY ascii "<acronym>ASCII</acronym>">
  <!ENTITY der "<acronym>DER</acronym>">
  <!ENTITY ssl "<acronym>SSL</acronym>">
  <!ENTITY x509 "<acronym>X.509</acronym>">
  <!ENTITY crl "<acronym>CRL</acronym>">
  <!ENTITY ocsp "<acronym>OCSP</acronym>">
  <!ENTITY NA "<acronym>N/A</acronym>">
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE">

  <!ENTITY dn "<acronym>DN</acronym>">
  <!ENTITY ca "<acronym>CA</acronym>">
]>

<book id="kleopatra" lang="&language;">

<bookinfo id="kleopatrainfo">
<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>2013-07-04</date>
<releaseinfo>2.1.1 (&kde; 4.11)</releaseinfo>

<abstract>
<para>
  &kleopatra; is a tool for managing <ulink url="https://en.wikipedia.org/wiki/X.509">&x509;</ulink> and <ulink url="https://en.wikipedia.org/wiki/Pretty_Good_Privacy#OpenPGP">&openpgp;</ulink> certificates.
</para>
</abstract>


<keywordset>
<keyword>KDE</keyword>
<keyword>Kapp</keyword>
<keyword>X509</keyword>
<keyword>OpenPGP</keyword>
<keyword>PGP</keyword>
<keyword>LDAP</keyword>
<keyword>gpg</keyword>
<keyword>gpgsm</keyword>
<keyword>certificate</keyword>
</keywordset>

</bookinfo>

<chapter id="introduction"> <title>Introduction</title>

<para>&kleopatra; is the &kde; tool for managing <ulink url="https://en.wikipedia.org/wiki/X.509">&x509;</ulink> and <ulink url="httpis://en.wikipedia.org/wiki/Pretty_Good_Privacy#OpenPGP">&openpgp;</ulink> certificates in
  the <ulink url="https://www.gnupg.org/documentation/manuals/gnupg/Invoking-GPGSM.html">&gpgsm;</ulink> and <ulink url="https://en.wikipedia.org/wiki/GNU_Privacy_Guard">&gpg;</ulink> keyboxes and for retrieving certificates from
&ldap; and other certificate 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, with whom
she had a child, Caesarion, unacknowledged as his heir.</para>

<para>The name was chosen since this program originates from the
<ulink url="https://www.gnupg.org/aegypten2/">&Auml;gypten
Projects</ulink> (&Auml;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, &eg; 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 <xref
linkend="view-hierarchical-key-list"/>.</para>

<para>You can see the details of any certificate by double-clicking it
or using <xref linkend="view-certificate-details"/>. 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; (&eg; using
&gpgsm;'s command line interface), you can refresh the view with <xref
linkend="view-redisplay"/>.</para>

<!-- no longer in kde 4
para>Since validating a key may take some time (&eg; 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 <ulink
url="https://www.gnupg.org/documentation/manuals/gnupg/Invoking-GPGSM.html#Invoking-GPGSM">
&gpgsm;</ulink> 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
<!--### xref-->
<menuchoice><guimenu>File</guimenu><guimenuitem>Lookup Certificates on Server</guimenuitem></menuchoice>
and enter some text (&eg; 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 <xref
linkend="file-import-certificates"/>. &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 <xref
linkend="file-import-certificates"/>,
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 <xref linkend="file-new-key-pair"/> starts the
<guilabel>Key Pair 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>&x509; key pairs are created locally, but certified centrally by a
certification authority (&ca;). &ca;s can certify other &ca;s, 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&mdash;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>

<!--FIXME modified copy from kgpg-->
<sect2 id="key-revoke">
<title>Revoking a key</title>

<para>A key pair that has expired can be brought back into an operational state
as long as you have access to the private key and the passphrase. To
reliably render a key unusable you need to revoke it. Revoking is done by
adding a special revocation signature to the key.</para>

<para>This revocation signature is stored in a separate file. This file can later be imported into
the keyring and is then attached to the key rendering it unusable. Please
note that to import this signature to the key no password is required.
Therefore you should store this revocation signature in a safe place,
usually one that is different from you key pair. It is a good advise to
use a place that is detached from your computer, either copy it to an
external storage device like an USB stick or print it out.</para>

<para>&kleopatra; does not provide a function to create such a revocation signature at any time, 
but you can do that with the &kde; application &kgpg; by choosing <menuchoice><guimenu>Keys</guimenu>
<guimenuitem>Revoke key</guimenuitem></menuchoice> and optionally importing the revocation signature
to your keyring immediately.</para>

<para>An alternative way of generating a revocation certificate is to use &gpg; directly from the command line: <userinput>gpg --output <replaceable>revocation_certificate</replaceable>.asc --gen-revoke <replaceable>your_key</replaceable></userinput>. The argument <replaceable>your_key</replaceable> must be a key specifier, either the key ID of your primary keypair or any part of a user ID that identifies your keypair.</para>

</sect2>

</sect1>


<!-- hopelessly outdated
<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 <xref linkend="certificates-delete"/>, as well
as manual handling of CRLs (<xref linkend="certificates-refresh-x509"/>,
<xref linkend="crls-clear-crl-cache"/>, <xref linkend="crls-dump-crl-cache"/>).
</para>

</sect1>
-->

</chapter>

<chapter id="menu"><title>Menu Reference</title>

<sect1 id="menufile"><title>File 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 <xref linkend="file-import-certificates"/>.</para>
</listitem>
</varlistentry>

        <varlistentry id="file-lookup-certificates">
          <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>
              <action>Searches for, and imports, certificates from
              certificate servers into the local keybox.</action> See
              <xref linkend="functions-search"/> for details.
            </para>
            <para>
              You need to have key servers configured for this to
              work. See
              <xref linkend="configuration-directory-services"/> for
              more details.
            </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> See
              <xref linkend="functions-search"/> for details.
            </para>
            <para>
              The format of the certificate file must be supported by
              &gpgsm;/&gpg;. Please refer to the &gpgsm; and &gpg;
              manuals 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 to a
              file.</action>
            </para>
            <para>
              The filename extension you choose for the export file
              name determines the format of the export file:
            </para>
            <itemizedlist>
              <listitem>
                <para>
                  For &openpgp; certificates,
                  <filename class="extension">gpg</filename> and
                  <filename class="extension">pgp</filename> will result
                  in a binary file, whereas
                  <filename class="extension">asc</filename> will result
                  in an &ascii;-armored file.
                </para>
              </listitem>
              <listitem>
                <para>
                  For &smime; certificates,
                  <filename class="extension">der</filename> will result
                  in a binary, &der;-encoded file, whereas
                  <filename class="extension">pem</filename> will result
                  in an &ascii;-armored file.
                </para>
              </listitem>
            </itemizedlist>
            <para>
              Unless multiple certificates are selected, &kleopatra;
              will propose
              <filename><replaceable>fingerprint</replaceable>.{asc,pem}</filename>
              as the export file name.
            </para>
            <para>
              This function is only available when one or more
              certificates have been selected.
            </para>
            <note>
              <para>
                This function exports only the public keys, even if
                the secret key is available. Use
                <xref linkend="file-export-secret-key"/> to export
                the secret keys into a file.
              </para>
            </note>
          </listitem>
        </varlistentry>

        <varlistentry id="file-export-secret-key">
          <term>
            <menuchoice>
              <guimenu>File</guimenu><guimenuitem>Export Secret Keys...</guimenuitem>
            </menuchoice>
          </term>
          <listitem>
            <para>
              <action>Exports the secret key to a file.</action>
            </para>
            <para>
              In the dialog that opens, you can choose whether to
              create a binary or an &ascii;-armored export file
              (<guilabel>ASCII armor</guilabel>). 
	      Next click on the folder icon at the right hand side of the 
	      <guilabel>Output file</guilabel> text box and select folder 
	      and name of the export file. When exporting
              &smime; secret keys, you can also choose the
              <guilabel>Passphrase charset</guilabel>. See the
              discussion of the
              <option>--p12-charset&nbsp;<replaceable>charset</replaceable></option>
              option in the &gpgsm; manual for more details.
            </para>
            <para>
              This function is only available when exactly one
              certificate has been selected, and the secret key for
              that certificate is available.
            </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 on the transport medium,
                among other things.
              </para>
            </warning>
          </listitem>
        </varlistentry>

        <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>
              <action>Publish the selected certificates on a
              keyserver</action> (&openpgp; only).
            </para>
            <para>
              The certificate is sent to the certificate server
              configured for &openpgp;
              (cf.&nbsp;<xref linkend="configuration-directory-services"/>),
              if that is set, otherwise to
              <systemitem class="systemname">keys.gnupg.net</systemitem>.
            </para>
            <para>
              This function is only available if at least one
              &openpgp; (and no &smime;) certificates have been
              selected.
            </para>
            <note>
              <!-- also appears in message box in -->
              <!-- commands/exportopenpgpcertificatestoserver.cpp -->
              <para>
                When &openpgp; certificates have been exported to a
                public directory server, it is nearly impossible to
                remove them again. Before exporting your certificate
                to a public directory server, make sure that you have
                created a revocation certificate so you can revoke the
                certificate if needed later.
              </para>
            </note>
            <note>
              <para>
                Most public &openpgp; certificate servers synchronize
                certificates amongst each other, so there is little
                point in sending to more than one.
              </para>
              <para>
                It can happen that a search on a certificate server
                turns up no results even though you just have sent
                your certificate there. This is because most public
                keyserver addresses use <acronym>DNS</acronym>
                round-robin to balance the load over multiple
                machines. These machines synchronize with each other,
                but usually only every 24 hours or so.
              </para>
            </note>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <menuchoice>
              <guimenu>File</guimenu><guimenuitem>Decrypt/Verify Files...</guimenuitem>
            </menuchoice>
          </term>
          <listitem>
            <para>
              <action>Decrypts files and/or verifies
              signatures</action> over files.
            </para>
<!--
            <para>
              See <xref linkend="function-decrypt-verify-files"/> for details.
            </para>
-->
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <menuchoice>
              <guimenu>File</guimenu><guimenuitem>Sign/Encrypt Files...</guimenuitem>
            </menuchoice>
          </term>
          <listitem>
            <para>
              <action>Signs and/or encrypts files.</action>
            </para>
<!--
            <para>
              See <xref linkend="function-sign-encrypt-files"/> for details.
            </para>
-->
          </listitem>
        </varlistentry>
<!--
Create Checksum Files...
Verify Checksum Files...
  missing-->
        <varlistentry>
          <term>
            <menuchoice>
              <shortcut><keycombo action="simul">&Ctrl;<keycap>W</keycap></keycombo></shortcut>
              <guimenu>File</guimenu><guimenuitem>Close</guimenuitem>
            </menuchoice>
          </term>
          <listitem>
            <para>
              <action>Closes &kleopatra;'s main window.</action> You
              can restore it from the system tray icon at any time.
            </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>View 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>Refreshes the certificate list.</action>
            </para>
            <para>
              Using this function is usually not necessary, as
              &kleopatra; monitors the file system for changes and
              automatically refreshes the certificate list when
              needed.
            </para>
          </listitem>
        </varlistentry>


        <varlistentry id="view-stop-operation">
          <term>
            <menuchoice>
              <shortcut><keycombo action="simul">&Esc;</keycombo></shortcut>
              <guimenu>View</guimenu><guimenuitem>Stop Operation</guimenuitem>
            </menuchoice>
          </term>
          <listitem>
            <para>
              <action>Stops (cancels) all pending operations,</action>
              &eg; a search, keylisting, or a download.
            </para>
            <para>
              This function is only available if at least one
              operation is active.
            </para>
            <note>
              <para>
                Due to backend limitations, sometimes operations will
                hang in such a way that this function won't be able to
                cancel them, right away, or at all.
              </para>
              <para>
                In such cases, the only way to restore order is to
                kill &scdaemon;, &dirmngr;, &gpgsm; and &gpg;
                processes, in that order, via the operating system
                tools (<command>top</command>, Task-Manager,
                &etc;), until the operation get unblocked.
              </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 only available if exactly one certificate is
selected.</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 certificate list mode.
</action></para>

<para>In hierarchical mode, certificates are arranged in
issuer/subject relation, so it is easy to see which certification
hierarchy a given certificate belongs to, 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>

            <para>
              This function toggles hierarchical mode per tab, &ie;
              each tab has its own hierarchy state. This is so that
              you can have both a flat and a hierarchical listing at
              hand, each in its own tab.
            </para>

            <note>
              <para>
                Hierarchical display is currently only implemented for
                &smime; certificates. There is disagreement amongst
                the developers regarding the correct way to display
                &openpgp; certificates hierarchically (basically,
                <quote>parent &equals; signer</quote> or <quote>parent
                &equals; signee</quote>).
              </para>
            </note>

</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><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>

<para>This function is only available when <xref
linkend="view-hierarchical-key-list"/> is on.</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><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>

<para>This function is only available when <xref
linkend="view-hierarchical-key-list"/> is on.</para>
</listitem>
</varlistentry>

</variablelist>

</sect1>

<sect1 id="menucertificates"><title>Certificates Menu</title>

      <variablelist>

        <varlistentry id="certificates-change-owner-trust">
          <term>
            <menuchoice>
              <guimenu>Certificates</guimenu><guimenuitem>Change Owner Trust...</guimenuitem>
            </menuchoice>
          </term>
          <listitem>
            <para>
              <action>Changes the Owner Trust of the selected
              &openpgp; certificate.</action>
<!--
              See <xref linkend="functions-manage-wot"/> for details.
-->
            </para>
            <para>
              This function is only available when exactly one
              &openpgp; certificate is selected.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry id="certificates-trust-root">
          <term>
            <menuchoice>
              <guimenu>Certificates</guimenu><guimenuitem>Trust Root Certificate</guimenuitem>
            </menuchoice>
          </term>
          <listitem>
            <para>
              <action>Marks this (&smime;) root certificate as trusted.</action>
            </para>
            <para>
              In some ways, this is the equivalent of <xref
              linkend="certificates-change-owner-trust"/> for &smime;
              root certificates. You can, however, only choose
              between&mdash;in &openpgp;
              terms&mdash;<quote>ultimate</quote> trust and
              <quote>never trust</quote>.
            </para>
            <note>
              <para>
                The backend (by way of &gpgagent;) will ask at root
                certificate import time whether to trust the imported
                root certificate. However, that function must be
                explicitly enabled in the backend configuration
                (<option>allow-mark-trusted</option> in
                <filename>gpg-agent.conf</filename>, or either
                <menuchoice><guimenu>GnuPG&nbsp;System</guimenu>
                <guisubmenu>GPG&nbsp;Agent</guisubmenu>
                <guimenuitem>Allow clients to mark keys as
                "trusted"</guimenuitem></menuchoice> or <link
                linkend="configuration-smime-validation-allow-mark-trusted"><menuchoice><guimenu>S/MIME&nbsp;Validation</guimenu>
                <guimenuitem>Allow to mark root certificates as
                trusted</guimenuitem></menuchoice></link> under <xref
                linkend="configuration"/>).
              </para>
              <para>
                Enabling that functionality in the backend can lead to
                popups from &pinentry; at inopportune times (&eg; when
                verifying signatures), and can thus block unattended
                email processing. For that reason, and because it is
                desirable to be able to <emphasis>distrust</emphasis>
                a trusted root certificate again, &kleopatra; allows
                manual setting of trust.
              </para>
            </note>
            <warning>
              <para>
                Due to lack of backend support for this function,
                &kleopatra; needs to work directly on the &gpgsm;
                trust database
                (<filename>trustlist.txt</filename>). When using this
                function, make sure no other crypto operations are in
                progress that could race with &kleopatra; for
                modifications to that database.
              </para>
            </warning>
            <para>
              This function is only available when exactly one &smime;
              root certificate is selected, and that certificate is
              not yet trusted.
            </para>
            <para>
              Use <xref linkend="certificates-distrust-root"/> to undo
              this function.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry id="certificates-distrust-root">
          <term>
            <menuchoice>
              <guimenu>Certificates</guimenu><guimenuitem>Distrust Root Certificate</guimenuitem>
            </menuchoice>
          </term>
          <listitem>
            <para>
              <action>Marks this (&smime;) root certificate as not trusted.</action>
            </para>
            <para>
              This function is only available when exactly one &smime;
              root certificate is selected, and that certificate is
              currently trusted.
            </para>
            <para>
              Used to undo <xref
              linkend="certificates-trust-root"/>. See there for
              details.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry id="certificates-certify">
          <term>
            <menuchoice>
              <guimenu>Certificates</guimenu><guimenuitem>Certify Certificate...</guimenuitem>
            </menuchoice>
          </term>
          <listitem>
            <para>
              <action>Allows you to certify another &openpgp;
              certificate.</action>
<!-- ### xref
              See <xref linkend="functions-manage-wot"/> for details.
-->
            </para>
            <para>
              This function is only available if exactly one &openpgp;
              certificate is selected.
            </para>
          </listitem>
        </varlistentry>


<!--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-certificate-filters"><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 (&eg; 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 &eg; 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-->

        <varlistentry>
          <term>
            <menuchoice>
              <guimenu>Certificates</guimenu><guimenuitem>Change Expiry Date...</guimenuitem>
            </menuchoice>
          </term>
          <listitem>
            <para>
              <action>Allows to change the expiry date of your &openpgp; certificate.</action>
            </para>
            <para>
              Use this function to extend the lifetime of your
              &openpgp; certificates as an alternative to either
              creating a new one, or using unlimited lifetime
              (<quote>never expires</quote>).
            </para>
            <para>
              This function is only available if exactly one &openpgp;
              certificate is selected, and the secret key is available
              for that certificate.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <menuchoice>
              <guimenu>Certificates</guimenu><guimenuitem>Change Passphrase...</guimenuitem>
            </menuchoice>
          </term>
          <listitem>
            <para>
              <action>Allows to change the passphrase of your secret key.</action>
            </para>
            <para>
              This function is only available if exactly one
              certificate is selected, and the secret key is available
              for that certificate. It requires a very recent backend,
              since we changed the implementation from direct calling
              of &gpg; and &gpgsm; to a &gpgme;-based one.
            </para>
            <note>
              <para>
                For security reasons, both the old as well as the new
                passphrase is asked for by &pinentry;, a separate
                process. Depending on the platform you are running on
                and on the quality of the &pinentry; implementation on
                that platform, it may happen that the &pinentry;
                window comes up in the background. So, if you select
                this function and nothing happens, check the operating
                system's task bar in case a &pinentry; window is open
                in the background.
              </para>
            </note>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <menuchoice>
              <guimenu>Certificates</guimenu><guimenuitem>Add User-ID...</guimenuitem>
            </menuchoice>
          </term>
          <listitem>
            <para>
              <action>Allows to add a new User-ID to your &openpgp; certificate.</action>
            </para>
            <para>
              Use this to add new identities to an existing
              certificate as an alternative to creating a new key
              pair. An &openpgp; user-ID has the following form:
            </para>
            <programlisting><replaceable>Real&nbsp;Name</replaceable>&nbsp;<optional>(<replaceable>Comment</replaceable>)</optional>&nbsp;&lt;<replaceable>Email</replaceable>&gt;</programlisting>
            <para>
              In the dialog that comes up when you select this
              function, &kleopatra; will ask you for each of the three
              parameters (<replaceable>Real&nbsp;Name</replaceable>,
              <replaceable>Comment</replaceable> and
              <replaceable>Email</replaceable>) separately, and
              display the result in a preview.
            </para>
            <note>
              <para>
                These parameters are subject to the
                same Administrator restrictions as in new
                certificates. See <xref linkend="functions-newkey"/>
                and <xref linkend="admin-certificate-request-wizard"/>
                for details.
              </para>
            </note>
            <para>
              This function is only available when exactly one
              &openpgp; certificate is selected, and the secret key is
              available for that certificate.
            </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 the selected certificates</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 <xref linkend="view-hierarchical-key-list"/>
              function to regain control over the lot of
              certificates.
            </para>
            <warning>
              <para>
                There is one exception to the above: When you delete
                one of your own certificates, you delete the secret
                key along with it. This implies that you will not be
                able to read past communication encrypted to you using
                this certificate, unless you have a backup somewhere.
              </para>
              <para>
                &kleopatra; will warn you when you attempt to delete a
                secret key.
              </para>
            </warning>
            <para>
              Due to the hierarchical nature of &smime; certificates,
              if you delete an &smime; issuer certificate (&ca; certificate),
              all subjects are deleted, too.<footnote><para>This is the same as a
              filesystem: When you delete a folder, you delete all
              files and folders in it, too.</para></footnote>
            </para>
            <para>
              Naturally, this function is only available if you
              selected at least one certificate.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry id="certificates-dump-certificate">
          <term>
            <menuchoice>
              <guimenu>Certificates</guimenu><guimenuitem>Dump Certificate</guimenuitem>
            </menuchoice>
          </term>
          <listitem>
            <para>
              <action>Shows all information that &gpgsm; has about the
              selected (&smime;) certificate.</action>
            </para>
            <para>
              See the discussion about
              <option>--dump-key&nbsp;<replaceable>key</replaceable></option>
              in the &gpgsm; manual for details about the output.
            </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>Tools 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;
              applications. If signing, encryption, or verification
              mysteriously stop working, you might find out why by
              looking at the log.
            </para>
            <para>
              This function is not available on &Windows;, since the
              underlying mechanisms are not implemented in the backend
              on that platform.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry id="certificates-refresh-openpgp">
          <term>
            <menuchoice>
              <guimenu>Tools</guimenu><guimenuitem>Refresh OpenPGP Certificates</guimenuitem>
            </menuchoice>
          </term>
          <listitem>
            <para>
              <action>Refreshes all &openpgp; certificates</action> by executing

              <programlisting><command>gpg&nbsp;<option>--refresh-keys</option></command></programlisting>

              After successful completion of the command, your local
              keystore will reflect the latest changes with respect to
              validity of &openpgp; certificates.
            </para>
            <para>
              See note under <xref
              linkend="certificates-refresh-x509"/> for some caveats.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry id="certificates-refresh-x509">
          <term>
            <menuchoice>
              <guimenu>Tools</guimenu><guimenuitem>Refresh X.509 Certificates</guimenuitem>
            </menuchoice>
          </term>
          <listitem>
            <para>
              <action>Refreshes all &smime; certificates</action> by executing

              <programlisting><!--
                --><command>gpgsm&nbsp;<!--
                  --><option>-k</option>&nbsp;<!--
                  --><option>--with-validation</option>&nbsp;<!--
                  --><option>--force-crl-refresh</option>&nbsp;<!--
                  --><option>--enable-crl-checks</option><!--
                  --></command></programlisting>

              After successful completion of the command, your local
              keystore will reflect the latest changes with respect to
              validity of &smime; certificates.
            </para>
            <note>
              <para>
                Refreshing &x509; or &openpgp; certificates implies
                downloading all certificates and &crl;s, 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>
            </note>
          </listitem>
        </varlistentry>

        <varlistentry id="file-import-crls">
          <term>
            <menuchoice>
              <guimenu>Tools</guimenu><guimenuitem>Import CRL From File...</guimenuitem>
            </menuchoice>
          </term>
          <listitem>
            <para>
              <action>Lets you manually import &crl;s from
              files.</action>
            </para>
            <para>
              Normally, Certificate Revocation Lists (&crl;s) 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 &dirmngr; tool must be in
                the search <envar>PATH</envar>. If this menu item is
                disabled, you should contact the system administrator
                and ask them to install &dirmngr;.
              </para>
            </note>
          </listitem>
        </varlistentry>

<!-- no longer provided
that is wrong
"Clear CRL Cache"+"Dump CRL Cache" are still in the gui of 4.5 + trunk
-->
<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 <xref linkend="certificates-refresh-x509"/> 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>
<!-- no longer provided
<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>Settings Menu</title>

<para>&kleopatra; has a default &kde; <guimenu>Settings</guimenu> menu as described in the 
<ulink url="help:/fundamentals/menus.html#menus-settings">&kde; Fundamentals</ulink> 
with one additional entry:</para>

      <variablelist>

        <varlistentry id="settings-self-test">
          <term>
            <menuchoice>
              <guimenu>Settings</guimenu><guimenuitem>Perform Self-Test</guimenuitem>
            </menuchoice>
          </term>
          <listitem>
            <para>
              <action>Performs a set of self-tests and presents their result.</action>
            </para>
            <para>
              This is the same set of tests that is run at startup by
              default. If you disabled startup-time self-tests, you
              can re-enable them here.
            </para>
<!-- ### xref
            <para>
              See <xref linkend="function-selftest"/> for details.
            </para>
-->
          </listitem>
        </varlistentry>

      </variablelist>

    </sect1> <!-- Settings Menu -->

<sect1 id="menuwindow"><title>Window 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>Help Menu</title>

<para>&kleopatra; has a default &kde; <guimenu>Help</guimenu> menu as described in the 
<ulink url="help:/fundamentals/menus.html#menus-help">&kde; Fundamentals</ulink>.</para>

</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>--uiserver-socket</option> <replaceable>argument</replaceable></term>
<listitem>
<para>Location of the socket the ui server is listening on</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>--daemon</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 (&x509;, 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 <xref
linkend="file-import-certificates"/>.</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>
<!-- comment for 4.5-->
<varlistentry>
<term><option>-E</option> <option>--encrypt-sign</option></term>
<listitem>
<para>Encrypt and/or sign file(s). Same as <option>--sign-encrypt</option>, do not use</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
      <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &kleopatra;...</guimenuitem></menuchoice>
<!-- ### xref
      or <xref linkend="systray-configure-kleopatra"/> or
      via the UI-Server (see <ref linkend="uiserver-start-confdialog"/>).
-->
    </para>
    <para>
      Each of its pages is described in the sections below.
    </para>

    <sect1 id="configuration-directory-services">
      <title>Configuring Directory Services</title>

      <para>
        On this page, you can configure which &ldap; servers to use
        for &smime; certificate searches, and which key servers to use
        for &openpgp; certificate searches.
      </para>
      <note>
        <para>
          This is simply a more user-friendly version of the same
          settings you also find in <xref
          linkend="configuration-gnupg-system"/>. Everything you can
          configure here, you can configure there, too.
        </para>
      </note>
      <note>
        <title>A Note On Proxy Settings</title>
        <para>
          Proxy settings can be configured for &http; and &ldap; in
          <xref linkend="configuration-smime-validation"/>, but only
          for &gpgsm;. For &gpg;, due to the complexity of keyserver
          options in &gpg; and lack of proper support for them in
          &gpgconf;, you currently need to modify the config file
          <filename>gpg.conf</filename> directly. Please refer to the
          &gpg; manual for details. &kleopatra; will preserve such
          settings, but does not yet allow to modify them in the &GUI;.
        </para>
      </note>
      <para>
        The <guilabel>Directory services</guilabel> table shows which
        servers are currently configured. Double-click on a cell in
        the table to change parameters of existing server entries.
      </para>
      <para>
        The meaning of the columns in the table is as follows:
      </para>
      <variablelist>
        <varlistentry id="configuration-directory-services-scheme">
          <term><guilabel>Scheme</guilabel></term> <!-- linebreak here'd show up in xref text :/ -->
          <listitem>
            <para>
              Determines the network protocol which is used to access
              the server. Often-used schemes include
              <guilabel>ldap</guilabel> (and its &ssl;-secured sibling
              <guilabel>ldaps</guilabel>) for &ldap; servers (common
              protocol for &smime;; the only one supported by
              &gpgsm;), and <guilabel>hkp</guilabel>, the Horowitz
              Keyserver Protocol, nowadays usually &http; Keyserver
              Protocol, a &http;-based protocol that virtually all
              public &openpgp; keyservers support.
            </para>
            <para>
              Please refer to the &gpg; and &gpgsm; manuals for a list
              of supported schemes.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry id="configuration-directory-services-server-name">
          <term><guilabel>Server Name</guilabel></term>
          <listitem>
            <para>
              The domain name of the server, &eg; <systemitem
              class="systemname">keys.gnupg.net</systemitem>.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry id="configuration-directory-services-server-port">
          <term><guilabel>Server Port</guilabel></term>
          <listitem>
            <para>
              The network port the server is listening on.
            </para>
            <para>
              This changes automatically to the default port when you
              change the <xref
              linkend="configuration-directory-services-scheme"/>,
              unless it was set to some non-standard port to begin
              with. If you changed the default port and cannot get it
              back, try setting <xref
              linkend="configuration-directory-services-scheme"/> to
              <userinput>http</userinput> and <xref
              linkend="configuration-directory-services-server-port"/>
              to <userinput>80</userinput> (the default for &http;),
              then take it from there.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry id="configuration-directory-services-base-dn">
          <term><guilabel>Base DN</guilabel></term>
          <listitem>
            <para>
              The Base-&dn; (only for &ldap; and &ldaps;), &ie; the
              root of the &ldap; hierarchy to start from. This is
              often also called <quote>search root</quote> or
              <quote>search base</quote>.
            </para>
            <para>
              It usually looks like <userinput>c=de,o=Foo</userinput>,
              given as part of the &ldap; &URL;.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry id="configuration-directory-services-user-name">
          <term><guilabel>User Name</guilabel></term>
          <listitem>
            <para>
              The user name, if any, to use for logging into the
              server.
            </para>
            <para>
              This column is only shown if the option <guilabel>Show
              user and password information</guilabel> (below the
              table) is checked.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry id="configuration-directory-services-password">
          <term><guilabel>Password</guilabel></term>
          <listitem>
            <para>
              The password, if any, to use for logging into the
              server.
            </para>
            <para>
              This column is only shown if the option <guilabel>Show
              user and password information</guilabel> (below the
              table) is checked.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry id="configuration-directory-services-x509">
          <term><guilabel>X.509</guilabel></term>
          <listitem>
            <para>
              Check this column if this entry should be used for
              &x509; (&smime;) certificate searches.
            </para>
            <para>
              Only &ldap; (and &ldaps;) servers are supported for
              &smime;.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry id="configuration-directory-services-openpgp">
          <term><guilabel>OpenPGP</guilabel></term>
          <listitem>
            <para>
              Check this column if this entry should be used for
              &openpgp; certificate searches.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
      <para>
        You can configure as many &smime; (&x509;) servers as you
        want, but only one &openpgp; server is allowed at any
        time. The &GUI; will enforce this.
      </para>
      <para>
        To add a new server, click on the <guibutton>New</guibutton>
        button. This duplicates the selected entry, if any, or else
        inserts a default &openpgp; server.  Then you can set the
        <xref linkend="configuration-directory-services-server-name"/>, the
        <xref linkend="configuration-directory-services-server-port"/>, the
        <xref linkend="configuration-directory-services-base-dn"/>, and the
        usual <xref linkend="configuration-directory-services-password"/> and
        <xref linkend="configuration-directory-services-user-name"/>,
        both of which are only needed if the server requires
        authentication.
      </para>
      <para>
        To directly insert an entry for &x509; certificates, use
        <menuchoice><guimenu>New</guimenu><!--
        --><guimenuitem>X.509</guimenuitem></menuchoice>; use
        <menuchoice><guimenu>New</guimenu><!--
        --><guimenuitem>OpenPGP</guimenuitem></menuchoice> for
        &openpgp;.
      </para>
      <para>
        To remove a server from the search list, select it in the
        list, then press the <guibutton>Delete</guibutton> 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 Appearance</title>

      <sect2 id="configuration-appearance-tooltips">
          <title>Configuring <guilabel>Tooltips</guilabel></title>

        <para>
          In the main certificate list, &kleopatra; can show details
          about a certificate in a tooltip. The information displayed
          is the same as in <!--link
          linkend="dialog-certificate-details-overview"-->the
          <guilabel>Overview</guilabel> tab of the
          <guilabel>Certificate Details</guilabel>
          dialog<!--/link-->. Tooltips, however, can be restricted to
          show only a subset of information for a less verbose
          experience.
        </para>
        <note>
          <para>
            The <guilabel>Key-ID</guilabel> is
            <emphasis>always</emphasis> shown. This is to ensure that
            tooltips for different certificates do, in fact, differ
            (this is especially important if only <xref
            linkend="tooltips-validity"/> has been selected).
          </para>
        </note>
        <para>
          You can independently enable or disable the following
          information sets:
        </para>
        <variablelist>
          <varlistentry id="tooltips-validity">
            <term><guilabel>Show validity</guilabel></term>
            <listitem>
              <para>
                Shows information about the validity of a certificate:
                its current status, issuer-&dn; (&smime; only), expiry
                dates (if any) and certificate usage flags.
              </para>
              <para>
                Example:
                <programlisting><!--
                  -->This certificate is currently valid.
<!--              -->Issuer:            CN=Test-ZS 7,O=Intevation GmbH,C=DE
<!--              -->Validity:          from 25.08.2009 10:42 through 19.10.2010 10:42
<!--              -->Certificate usage: Signing EMails and Files, Encrypting EMails and Files
<!--              -->Key-ID:            DC9D9E43<!--
                  --></programlisting>
              </para>
            </listitem>
          </varlistentry>
          <varlistentry id="tooltips-owner">
            <term><guilabel>Show owner information</guilabel></term>
            <listitem>
              <para>
                Shows information about the owner of the certificate:
                subject-&dn; (&smime; only), user-IDs (including
                emails addresses) and ownertrust (&openpgp; only).
              </para>
              <para>
                &openpgp; example:
                <programlisting><!--
                  -->User-ID:           Gpg4winUserA &lt;gpg4winusera@test.hq&gt;
<!--              -->Key-ID:            C6BF6664
<!--              -->Ownertrust:        ultimate<!--
                  --></programlisting>
                &smime; example:
                <programlisting><!--
                  -->Subject:           CN=Gpg4winTestuserA,OU=Testlab,O=Gpg4win Project,C=DE
<!--              -->a.k.a.:            Gpg4winUserA@test.hq
<!--              -->Key-ID:            DC9D9E43<!--
                  --></programlisting>
              </para>
            </listitem>
          </varlistentry>
          <varlistentry id="tooltips-details">
            <term><guilabel>Show technical details</guilabel></term>
            <listitem>
              <para>
                Shows technical information about the certificate:
                serial number (&smime; only), type, fingerprint and storage location.
              </para>
              <para>
                Example:
                <programlisting><!--
                  -->Serial Number:     27
<!--              -->Certificate type:  1,024-bit RSA (secret certificate available)
<!--              -->Key-ID:            DC9D9E43
<!--              -->Fingerprint:       854F62EEEBB41BFDD3BE05D124971E09DC9D9E43
<!--              -->Stored:            on this computer<!--
                  --></programlisting>
              </para>
            </listitem>
          </varlistentry>
        </variablelist>

      </sect2>

      <sect2 id="configuration-appearance-certificate-filters">
        <title>Configuring <guilabel>Certificate Categories</guilabel></title>

        <para>
          &kleopatra; allows you to customize the appearance of
          certificates in the list view. This includes showing a small
          icon, but you can also influence the foreground (text) and
          background colors, as well as the font.
        </para>
        <para>
          Each certificate category in the list is assigned a set of
          colors, an icon (optional) and a font in which certificates
          from 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 set or change the icon of a category, select it in the
          list, and press the <guibutton>Set Icon...</guibutton>
          button. The standard &kde; icon selection dialog will appear
          where you can select an existing icon from the &kde;
          collection, or load a custom one.
        </para>
        <para>
          To remove an icon again, you need to press the
          <guibutton>Default Appearance</guibutton> button.
        </para>
        <para>
          To change the text (&ie; foreground) color of a category,
          select it in the list, and press the <guibutton>Set Text
          Color...</guibutton> button. The standard &kde; color
          selection dialog will appear where you can select an
          existing color or create a new one.
        </para>
        <para>
          Changing the background color is done in the same way, just press
          <guibutton>Set Background Color...</guibutton> 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 <guibutton>Set
          Font...</guibutton> button. The standard &kde; font
          selection dialog will appear where you can select the new
          font.
        </para>
        <note>
          <para>
            You can still use the font modifiers to change the custom
            font, just as for modifying the standard font.
          </para>
        </note>
        <para>
          To switch back to the standard font, you need to press the
          <guibutton>Default Appearance</guibutton> button.
        </para>

      </sect2>

      <sect2 id="configuration-dn-order">
        <title>Configuring <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 form of the
attribute (&eg; <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>

      </sect2>

    </sect1>

    <sect1 id="configuration-crypto-operations">
      <title>Configuring Crypto Operations</title>

      <sect2 id="configuration-crypto-operations-email">
        <title>Configuring <guilabel>EMail Operations</guilabel></title>

        <para>
          Here you can configure some aspects of the email operations
          of &kleopatra;'s &uiserver;. Currently, you can only
          configure whether or not to use <quote>Quick Mode</quote> for
          signing and encrypting emails, individually.
        </para>
        <para>
          When <quote>Quick Mode</quote> is enabled, no dialog is
          shown when signing (encrypting) emails, respectively, unless
          there is a conflict that needs manual resolution.
        </para>

      </sect2>

      <sect2 id="configuration-crypto-operations-file">
        <title>Configuring <guilabel>File Operations</guilabel></title>

        <para>
          Here you can configure some aspects of the file operations
          of &kleopatra;'s &uiserver;. Currently, you can only choose
          the checksum program to use for <!--link ### xref
          linkend="uiserver-checksum-create-files"--><command>CHECKSUM_CREATE_FILES</command><!--/link-->.
        </para>
        <para>
          Use <guilabel>Checksum program to use</guilabel> to choose
          which of the configured checksum programs should be used
          when creating checksum files.
        </para>
        <para>
          When verifying checksums, the program to use is
          automatically found, based on the names of the checksum files
          found.
        </para>
        <note>
          <para>
            The administrator and power user can completely define
            which checksum programs to make available to &kleopatra;
            through so-called <quote>Checksum Definitions</quote> in
            the config file. See <xref linkend="admin-checksum-definitions"/>
            in <xref linkend="admin"/> for details.
          </para>
        </note>

      </sect2>

    </sect1>

    <sect1 id="configuration-smime-validation">
    <!-- keep in sync with section configure-security-smime-validation from kmail configure.docbook
    both apps have the same page in settings-->
      <title>Configuring aspects of S/&MIME; Validation</title>

      <para>
        On this page, you can configure certain aspects of the
        validation of &smime; certificates.
      </para>
      <note>
        <para>
          For the most part, this is simply a more user-friendly
          version of the same settings you also find in
          <xref linkend="configuration-gnupg-system"/>. Everything you
          can configure here, you can configure there, too, with the
          exception of
          <xref linkend="configuration-smime-validation-refresh-interval"/>,
          which is &kleopatra;-specific.
        </para>
      </note>
      <para>
        The meaning of the options is as follows:
      </para>

      <sect2 id="configuration-smime-validation-interval-checking">
        <title>Configuring interval certificate checking</title>

        <variablelist>
          <varlistentry id="configuration-smime-validation-refresh-interval">
            <term><guilabel>Check certificate validity every
                <replaceable>N</replaceable> hours</guilabel></term>
            <listitem>
              <para>
                This option enables interval checking of certificate
                validity. You can also choose the checking interval (in
                hours). The effect of interval checking is the same as
                <xref linkend="view-redisplay"/>; there is no provision
                for interval scheduling of <xref
                  linkend="certificates-refresh-openpgp"/> or <xref
                  linkend="certificates-refresh-x509"/>.
              </para>
              <note>
                <para>
                  Validation is performed implicitly whenever significant
                  files in <filename>~/.gnupg</filename> change. This
                  option, just like <xref linkend="certificates-refresh-openpgp"/>
                  and <xref linkend="certificates-refresh-x509"/>, therefore only
                  affects external factors of certificate validity.
                </para>
              </note>
            </listitem>
          </varlistentry>
        </variablelist>

      </sect2>

      <sect2 id="configuration-smime-validation-method">
        <title>Configuring validation method</title>

        <variablelist>
          <varlistentry id="configuration-smime-validation-use-crls">
            <term><guilabel>Validate certificates using CRLs</guilabel></term>
            <listitem>
              <para>
                If this option is selected, &smime; certificates are
                validated using Certificate Revocation Lists (&crl;s).
              </para>
              <para>
                See <xref linkend="configuration-smime-validation-use-ocsp"/>
                for alternative method of certificate validity checking.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry id="configuration-smime-validation-use-ocsp">
            <term><guilabel>Validate certificates online (OCSP)</guilabel></term>
            <listitem>
              <para>
                If this option is selected, &smime; certificates are
                validated online using the Online Certificates Status
                Protocol (&ocsp;).
              </para>
              <warning>
                <para>
                  When choosing this method, a request is sent to the
                  server of the &ca; more or less each time you send or
                  receive a cryptographic message, thus theoretically
                  allowing the certificate issuing agency to track whom
                  you exchange (&eg;) mails with.
                </para>
              </warning>
              <para>
                To use this method, you need to enter the &URL; of the
                &ocsp; responder into <xref linkend="configuration-smime-validation-ocsp-url"/>.
              </para>
              <para>
                See <xref linkend="configuration-smime-validation-use-ocsp"/>
                for a more traditional method of certificate validity
                checking that does not leak information about whom you
                exchange messages with.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry id="configuration-smime-validation-ocsp-url">
            <term><guilabel>OCSP responder URL</guilabel></term>
            <listitem>
              <para>
                Enter here the address of the server for online
                validation of certificates (&ocsp; responder). The &URL;
                usually starts with <literal>http://</literal>.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry id="configuration-smime-validation-ocsp-signature">
            <term><guilabel>OCSP responder signature</guilabel></term>
            <listitem>
              <para>
                Choose here the certificate with which the &ocsp; server
                signs its replies.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry id="configuration-smime-validation-ocsp-ignore-service-url">
            <term><guilabel>Ignore service URL of certificates</guilabel></term>
            <listitem>
              <para>
                Each &smime; certificate usually contains the &URL; of
                its issuer's &ocsp; responder (<xref
                  linkend="certificates-dump-certificate"/> will reveal
                whether a given certificate contains it).
              </para>
              <para>
                Checking this option makes &gpgsm; ignore those &URL;s
                and only use the one configured above.
              </para>
              <para>
                Use this to &eg; enforce use of a company-wide &ocsp;
                proxy.
              </para>
            </listitem>
          </varlistentry>

        </variablelist>

      </sect2>

      <sect2 id="configuration-smime-validation-options">
        <title>Configuring validation options</title>

        <variablelist>
          <varlistentry id="configuration-smime-validation-dont-check-cert-policy">
            <term><guilabel>Do not check certificate policies</guilabel></term>
            <listitem>
              <para>
                By default, &gpgsm; uses the file
                <filename>~/.gnupg/policies.txt</filename> to check if a
                certificate policy is allowed. If this option is
                selected, policies are not checked.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry id="configuration-smime-validation-never-consult-crl">
            <term><guilabel>Never consult a CRL</guilabel></term>
            <listitem>
              <para>
                If this option is checked, Certificate Revocation Lists
                are never used to validate &smime; certificates.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry id="configuration-smime-validation-allow-mark-trusted">
            <term><guilabel>Allow to mark root certificates as trusted</guilabel></term>
            <listitem>
            <para>
                If this option is checked while a root &ca; certificate is
                being imported, you will be asked to confirm its
                fingerprint and to state whether or not you consider this
                root certificate to be trusted.
              </para>
              <para>
                A root certificate needs to be trusted before the
                certificates it certified become trusted, but lightly
                allowing trusted root certificates into your certificate
                store will undermine the security of the system.
              </para>
              <note>
                <para>
                  Enabling this functionality in the backend can lead to
                  popups from &pinentry; at inopportune times (&eg; when
                  verifying signatures), and can thus block unattended
                  email processing. For that reason, and because it is
                  desirable to be able to <emphasis>distrust</emphasis>
                  a trusted root certificate again, &kleopatra; allows
                  manual setting of trust using
                  <xref linkend="certificates-trust-root"/> and
                  <xref linkend="certificates-distrust-root"/>.
                </para>
                <para>
                  This setting here does not influence the &kleopatra;
                  function.
                </para>
              </note>
            </listitem>
          </varlistentry>
          <varlistentry id="configuration-smime-validation-fetch-missing-issuers">
            <term><guilabel>Fetch missing issuer certificates</guilabel></term>
            <listitem>
              <para>
                If this option is checked, missing issuer certificates
                are fetched when necessary (this applies to both
                validation methods, &crl;s and &ocsp;).
              </para>
            </listitem>
          </varlistentry>
        </variablelist>

      </sect2>

      <sect2 id="configuration-smime-validation-http-options">
        <title>Configuring &http; request options</title>

        <variablelist>
          <varlistentry id="configuration-smime-validation-disable-http">
            <term><guilabel>Do not perform any HTTP requests</guilabel></term>
            <listitem>
              <para>
                Entirely disables the use of &http; for &smime;.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry id="configuration-smime-validation-ignore-http-dp">
            <term><guilabel>Ignore HTTP CRL distribution point of certificates</guilabel></term>
            <listitem>
              <para>
                When looking for the location of a &crl;, the
                to-be-tested certificate usually contains what are
                known as <quote>&crl; Distribution Point</quote>
                (<acronym>DP</acronym>) entries, which are &URL;s
                describing the way to access the &crl;. The first-found
                <acronym>DP</acronym> entry is used.
              </para>
              <para>
                With this option, all entries using the &http; scheme
                are ignored when looking for a suitable
                <acronym>DP</acronym>.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry id="configuration-smime-validation-honor-http-proxy">
            <term><guilabel>Use system HTTP proxy</guilabel></term>
            <listitem>
              <para>
                If this option is selected, the value of the &http;
                proxy shown on the right (which comes from the
                environment variable <envar>http_proxy</envar>) will
                be used for any &http; request.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry id="configuration-smime-validation-custom-http-proxy">
            <term><guilabel>Use this proxy for HTTP requests</guilabel></term>
            <listitem>
              <para>
                If no system proxy is set, or you need to use a
                different proxy for &gpgsm;, you can enter its
                location here.
              </para>
              <para>
                It will be used for all &HTTP; requests relating to
                S/&MIME;.
              </para>
              <para>
                The syntax is
                <userinput><replaceable>host</replaceable><literal>:</literal><replaceable>port</replaceable></userinput>,
                &eg; <userinput>myproxy.nowhere.com:3128</userinput>.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>

      </sect2>

      <sect2 id="configuration-smime-validation-ldap-options">
        <title>Configuring &ldap; request options</title>

        <variablelist>
          <varlistentry id="configuration-smime-validation-disable-ldap">
            <term><guilabel>Do not perform any LDAP requests</guilabel></term>
            <listitem>
              <para>
                Entirely disables the use of &ldap; for &smime;.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry id="configuration-smime-validation-ignore-ldap-dp">
            <term><guilabel>Ignore LDAP CRL distribution point of certificates</guilabel></term>
            <listitem>
              <para>
                When looking for the location of a &crl;, the
                to-be-tested certificate usually contains what are
                known as "&crl; Distribution Point"
                (<acronym>DP</acronym>) entries, which are &URL;s
                describing the way to access the &crl;. The first
                found <acronym>DP</acronym> entry is used.
              </para>
              <para>
                With this option, all entries using the &ldap; scheme
                are ignored when looking for a suitable
                <acronym>DP</acronym>.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry id="configuration-smime-validation-custom-ldap-proxy">
            <term><guilabel>Primary host for LDAP requests</guilabel></term>
            <listitem>
              <para>
                Entering an &ldap; server here will make all &ldap;
                requests go to that server first. More precisely, this
                setting overrides any specified
                <replaceable>host</replaceable> and
                <replaceable>port</replaceable> part in an &ldap;
                &URL; and will also be used if
                <replaceable>host</replaceable> and
                <replaceable>port</replaceable> have been omitted from
                the &URL;.
              </para>
              <para>
                Other &ldap; servers will be used only if the
                connection to the <quote>proxy</quote> failed. The
                syntax is
                <userinput><replaceable>host</replaceable></userinput>
                or
                <userinput><replaceable>host</replaceable><literal>:</literal><replaceable>port</replaceable></userinput>. If
                <replaceable>port</replaceable> is omitted, port 389
                (standard &ldap; port) is used.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>

      </sect2>

    </sect1>

    <sect1 id="configuration-gnupg-system">
    <!-- kleopatra + kmail have the this page in settings-->

      <title>Configuring the &gnupg; System</title>

      <para>
        This part of the dialog is auto-generated from the output of
        <command>gpgconf <option>--list-components</option></command>
        and, for each <replaceable>component</replaceable> that the
        above command returns, the output of <command>gpgconf
        <option>--list-options</option>
        <replaceable>component</replaceable></command>.
      </para>
      <note>
        <para>
          The most useful of these options have been duplicated as
          separate pages in the &kleopatra; config dialog. See <xref
          linkend="configuration-directory-services"/> and <xref
          linkend="configuration-smime-validation"/> for the two
          dialog pages which contain selected options from this part
          of the dialog.
        </para>
      </note>
      <para>
        The exact content of this part of the dialog depends on the
        version of the &gnupg; backend you have installed and,
        potentially, the platform you run on. Thus, we will only
        discuss the general layout of the dialog, including the
        mapping from &gpgconf; option to &kleopatra; &GUI; control.
      </para>
      <para>
        &gpgconf; returns configuration information for multiple
        components. Inside each component, individual options are
        combined into groups.
      </para>
      <para>
        &kleopatra; displays one tab per component reported by
        &gpgconf;; groups are headed by a horizontal line displaying
        the group name as returned from &gpgconf;.
      </para>
      <para>
        Each &gpgconf; option has a type. Except for certain
        well-known options which &kleopatra; backs with specialised
        controls for a better user experience, the mapping between
        &gpgconf; types and &kleopatra; controls is as follows:
      </para>
      <table id="table-gpgconf-types">
	<title>Mapping From &gpgconf; Types To &GUI; Controls</title>
	<tgroup cols="3">
          <colspec colname="type"/>
	  <colspec colname="lists" align="center"/>
          <colspec colname="non-lists" align="center"/>
	  <thead>
	    <row>
	      <entry morerows="1">&gpgconf; type</entry>
              <entry namest="lists" nameend="non-lists">&kleopatra; control</entry>
            </row>
            <row>
	      <entry>for lists</entry>
	      <entry>for non-lists</entry>
	    </row>
	  </thead>
	  <!--tfoot/-->
	  <tbody>
	    <row>
	      <entry><literal>none</literal></entry>
	      <entry>Spinbox (<quote>count</quote>-semantics)</entry>
	      <entry>Checkbox</entry>
	    </row>
            <row>
              <entry><literal>string</literal></entry>
              <entry>&NA;</entry>
              <entry>Lineedit</entry>
            </row>
            <row>
              <entry><literal>int32</literal></entry>
              <entry morerows="1">Lineedit (unformatted)</entry>
              <entry morerows="1">Spinbox</entry>
            </row>
            <row>
              <entry><literal>uint32</literal></entry>
            </row>
            <row>
              <entry><literal>pathname</literal></entry>
              <entry>&NA;</entry>
              <entry>specialised control</entry>
            </row>
            <row>
              <entry><literal>ldap server</literal></entry>
              <entry>specialised control</entry>
              <entry>&NA;</entry>
            </row>
            <row>
              <entry><literal>key fingerprint</literal></entry>
              <entry morerows="3" namest="lists" nameend="non-lists">&NA;</entry>
            </row>
            <row>
              <entry><literal>pub key</literal></entry>
            </row>
            <row>
              <entry><literal>sec key</literal></entry>
            </row>
            <row>
              <entry><literal>alias list</literal></entry>
            </row>
          </tbody>
        </tgroup>
      </table>
      <para>
        See the &gpgconf; manual for more information about what you
        can configure here, and how.
      </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>

<sect2 id="admin-certificate-request-wizard-dn"><title>Customizing the &dn; fields</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>

</sect2>

      <sect2 id="admin-certificate-request-wizard-keys">

        <title>Restricting the Types of Keys a User is Allowed to Create</title>

        <para>
          &kleopatra; also allows to restrict which type of
          certificates a user is allowed to create. Note, however,
          that an easy way around these restrictions is to just create
          one on the command line.
        </para>

        <sect3 id="admin-certificate-request-wizard-keys-type">

          <title>Public Key Algorithms</title>

          <para>
            To restrict the public key algorithm to use, add the
            config key <varname>PGPKeyType</varname> (and
            <varname>CMSKeyType</varname>, but only
            <acronym>RSA</acronym> is supported for
            <acronym>CMS</acronym> anyway) to the
            <literal>CertificateCreationWizard</literal> section of
            <filename>kleopatrarc</filename>.
          </para>

          <para>
            The allowed values are <literal>RSA</literal> for
            <acronym>RSA</acronym> keys, <literal>DAS</literal> for
            <acronym>DSA</acronym> (sign-only) keys, and
            <literal>DSA+ELG</literal> for a <acronym>DSA</acronym>
            (sign-only) key with an Elgamal subkey for encryption.
          </para>

          <para>
            The default is read from &gpgconf; or else
            <literal>RSA</literal> if &gpgconf; doesn't provide a
            default.
          </para>

        </sect3>

        <sect3 id="admin-certificate-request-wizard-keys-size">

          <title>Public Key Size</title>

          <para>
            To restrict the available keys sizes for a public
            algorithm, add the config key
            <varname><replaceable>&lt;ALG&gt;</replaceable>KeySizes</varname>
            (where <replaceable>ALG</replaceable> may be
            <literal>RSA</literal>, <literal>DSA</literal> or
            <literal>ELG</literal>) to the
            <literal>CertificateCreationWizard</literal> section of
            <filename>kleopatrarc</filename>, containing a
            comma-separated list of keysizes (in bits). A default may
            be indicated by prefixing the keysize with a hyphen
            (<literal>-</literal>).
          </para>

          <para>
            <programlisting>
            RSAKeySizes = 1536,-2048,3072
            </programlisting>
          </para>


          <para>
            The above would restrict allowed <acronym>RSA</acronym>
            key sizes to 1536, 2048 and 3072, with 2048 the default.
          </para>

          <para>
            In addition to the sizes themselves, you may also specify
            labels for each of the sizes. Simply set the config key
            <varname><replaceable>ALG</replaceable>KeySizeLabels</varname>
            to a comma-separated list of labels.
          </para>

          <para>
            <programlisting>
                RSAKeySizeLabels = weak,normal,strong
            </programlisting>
          </para>

          <para>
            The above, in connection with the previous example, would
            print something like the following options for selection:
            <programlisting>
              weak (1536 bits)
              normal (2048 bits)
              strong (3072 bits)
            </programlisting>
          </para>

          <para>
            The defaults are as if the following was in effect:
            <programlisting>
              RSAKeySizes = 1536,-2048,3072,4096
              RSAKeySizeLabels =
              DSAKeySizes = -1024,2048
              DSAKeySizeLabels = v1,v2
              ELGKeySizes = 1536,-2048,3072,4096
            </programlisting>
          </para>

        </sect3>

      </sect2>

    </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-certificate-filters">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-certificate-filters">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-certificate-filters">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 (&eg; 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>&nbsp;=&nbsp;<literal>is</literal>),
		has anything but
		(<replaceable>prefix</replaceable>&nbsp;=&nbsp;<literal>is-not</literal>),
		has at least
		(<replaceable>prefix</replaceable>&nbsp;=&nbsp;<literal>is-at-least</literal>),
		or has at most
		(<replaceable>prefix</replaceable>&nbsp;=&nbsp;<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, &eg;
        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>

    <sect1 id="admin-archive-definitions">

      <title>Configuring Archivers for Use with Sign/Encrypt Files</title>

      <para>
        &kleopatra; allows the administrator (and power-user) to
        configure the list of archivers that are presented in the
        Sign/Encrypt Files dialog.
      </para>

      <para>
        Each archiver is defined in
        <filename>libkleopatrarc</filename> as a separate
        <literal>Archive&nbsp;Definition&nbsp;#<replaceable>n</replaceable></literal>
        group, with the following mandatory keys:
      </para>

      <variablelist>

        <varlistentry id="archive-definition-extensions">
          <term><literal>extensions</literal></term>
          <listitem>
            <para>
              A comma-separated list of filename extensions that
              usually indicate this archive format.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry id="archive-definition-id">
          <term><literal>id</literal></term>
          <listitem>
            <para>
              A unique ID used to identify this archiver
              internally. If in doubt, use the name of the command.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry id="archive-definition-Name">
          <term><literal>Name</literal> (translated)</term>
          <listitem>
            <para>
              The user-visible name of this archiver, as shown in the
              corresponding drop-down menu of the Sign/Encrypt Files
              dialog.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry id="archive-definition-pack-command">
          <term><literal>pack-command</literal></term>
          <listitem>
            <para>
              The actual command to archive files. You can use any
              command, as long as no shell is required to execute
              it. The program file is looked up using the
              <envar>PATH</envar> environment variable, unless you
              use an absolute file path. Quoting is supported as if a
              shell was used:
              <programlisting>pack-command="/opt/ZIP v2.32/bin/zip" -r -</programlisting>
            </para>
          </listitem>
        </varlistentry>

      </variablelist>

      <note id="backslashes-in-config-keys">
        <para>
          Since backslash (<literal>\</literal>) is an escape
          character in &kde; config files, you need to double them when
          they appear in path names:
          <programlisting>pack-command=C:\\Programs\\GNU\\tar\\gtar.exe&nbsp;...</programlisting>

          However, for the command itself (as opposed to its
          arguments), you may just use forward slashes
          (<literal>/</literal>) as path separators on all platforms:
          <programlisting>pack-command=C:/Programs/GNU/tar/gtar.exe&nbsp;...</programlisting>

          This is not supported in arguments, as most &Windows; programs
          use the forward slash for options. For example, the
          following will not work, since
          <literal>C:/myarchivescript.bat</literal> is an argument to
          <command>cmd.exe</command>, and <literal>/</literal> is not
          converted to <literal>\</literal> in arguments, only
          commands:

          <programlisting>pack-command=cmd.exe C:/myarchivescript.bat</programlisting>
          This needs, instead, to be written as:
          <programlisting>pack-command=cmd.exe C:\\myarchivescript.bat</programlisting>
        </para>
      </note>

      <sect2 id="admin-archive-definitions-filename-passing">

      <title>Input Filename Passing for <literal>pack-command</literal></title>

      <para>
        There are three ways to pass filenames to the pack
        command. For each of these,
        <literal>pack-command</literal> provides a particular syntax:
      </para>

      <orderedlist>

        <listitem>
          <para>As command-line arguments.</para>
            <para>
              Example (tar):
              <programlisting>pack-command=tar cf -</programlisting>
              Example (zip):
              <programlisting>pack-command=zip -r - %f</programlisting>
              In this case, filenames are passed on the command line,
              just like you would when using the command
              prompt. &kleopatra; does not use a shell to execute the
              command. Therefore, this is a safe way of passing
              filenames, but it might run into command line length
              restrictions on some platforms.

              A literal <literal>%f</literal>, if present, is replaced
              by the names of the files to archive. Otherwise,
              filenames are appended to the command line. Thus, the
              zip Example above could equivalently be written like this:
              <programlisting>pack-command=zip -r -</programlisting>
            </para>
        </listitem>

        <listitem>
          <para>Via standard-in, separated by newlines: prepend <literal>|</literal>.</para>
            <para>
              Example (&GNU;-tar):
              <programlisting>pack-command=|gtar cf - -T-</programlisting>
              Example (ZIP):
              <programlisting>pack-command=|zip -@ -</programlisting>

              In this case, filenames are passed to the archiver on
              <acronym>stdin</acronym>, one per line. This avoids
              problems on platforms which place a low limit on the
              number of command line arguments that are allowed, but
              fails when filenames, in fact, contain newlines.
            </para>
            <note>
              <para>
                &kleopatra; currently only supports
                <acronym>LF</acronym> as a newline separator, not
                <acronym>CRLF</acronym>. This might change in future
                versions, based on user feedback.
              </para>
            </note>
        </listitem>

        <listitem>
          <para>Via standard-in, separated by NUL-bytes: prepend <literal>0|</literal>.</para>
            <para>
              Example (&GNU;-tar):
              <programlisting>pack-command=0|gtar cf - -T- --null</programlisting>
              This is the same as above, except that NUL bytes are
              used to separate filenames. Since NUL bytes are
              forbidden in filenames, this is the most robust way of
              passing filenames, but not all archivers support it.
            </para>
        </listitem>

      </orderedlist>

      </sect2> <!-- Input Filename Passing for pack-command -->

    </sect1> <!-- Archive Definitions -->

    <sect1 id="admin-checksum-definitions">

      <title>Configuring Checksum Programs for Use with Create/Verify Checksums</title>

      <para>
        &kleopatra; allows the administrator (and power-user) to
        configure the list of checksum programs that the user can
        choose from in the config dialog and that &kleopatra; is able
        to auto-detect when asked to verify a given file's checksum.
      </para>

      <note>
        <para>
          To be usable by &kleopatra;, output of checksum programs
          (both the written checksum file, as well as the output on
          <acronym>stdout</acronym> when verifying checksums) needs to
          be compatible with &GNU;
          <command>md5sum</command> and
          <command>sha1sum</command>.
        </para>

        <para>
          Specifically, the checksum file needs to be line-based with
          each line having the following format:

          <programlisting><replaceable>CHECKSUM</replaceable> ' ' ( ' ' | '*' ) <replaceable>FILENAME</replaceable></programlisting>

          where <replaceable>CHECKSUM</replaceable> consists of
          hex-characters only. If <replaceable>FILENAME</replaceable>
          contains a newline character, the line must instead read:

          <programlisting>\<replaceable>CHECKSUM</replaceable> ' ' ( ' ' | '*' ) <replaceable>ESCAPED-FILENAME</replaceable></programlisting>

          where <replaceable>ESCAPED-FILENAME</replaceable> is the
          filename with newlines replaced by <literal>\n</literal>s,
          and backslashes doubled
          (<literal>\</literal>&#x21A6;<literal>\\</literal>).
        </para>

        <para>
          Similarly, the output of
          <xref linkend="checksum-definition-verify-command"/> must be of the form

          <programlisting><replaceable>FILENAME</replaceable> ( ': OK' | ': FAILED' )</programlisting>

          separated by newlines. Newlines and other characters are
          <emphasis>not</emphasis> escaped in the output.<!--
          --><footnote>
            <para>
              Yes, these programs were not written with graphical
              frontends in mind, and &kleopatra; will fail to
              correctly parse pathological filenames that contain
              ":&nbsp;OK" plus newline in them.
            </para>
          </footnote>
        </para>
      </note>

      <para>
        Each checksum program is defined in
        <filename>libkleopatrarc</filename> as a separate
        <literal>Checksum&nbsp;Definition&nbsp;#<replaceable>n</replaceable></literal>
        group, with the following mandatory keys:
      </para>

      <variablelist>

        <varlistentry id="checksum-definition-file-patterns">
          <term><literal>file-patterns</literal></term>
          <listitem>
            <para>
              A list of regular expressions that describe which files
              should be considered checksum files for this checksum
              program. The syntax is the one used for string lists in
              &kde; config files.
              <note>
                <para>
                  Since regular expressions usually contain
                  backslashes, care must be taken to properly escape
                  them in the config file. The use of a config file
                  editing tool is recommended.
                </para>
              </note>
              The platform defines whether the patterns are treated
              case-sensitive or case-insensitive.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry id="checksum-definition-output-file">
          <term><literal>output-file</literal></term>
          <listitem>
            <para>
              The typical output filename for this checksum program
              (should match one of the
              <xref linkend="checksum-definition-file-patterns"/>, of
              course). This is what &kleopatra; will use as the
              output filename when creating checksum files of this
              type.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry id="checksum-definition-id">
          <term><literal>id</literal></term>
          <listitem>
            <para>
              A unique ID used to identify this checksum program
              internally. If in doubt, use the name of the command.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry id="checksum-definition-Name">
          <term><literal>Name</literal> (translated)</term>
          <listitem>
            <para>
              The user-visible name of this checksum program, as shown
              in the drop-down menu in &kleopatra;'s config dialog.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry id="checksum-definition-create-command">
          <term><literal>create-command</literal></term>
          <listitem>
            <para>
              The actual command with which to create checksum
              files. The syntax, restrictions and argument passing
              options are the same as described for
              <xref linkend="archive-definition-pack-command"/> in
              <xref linkend="admin-archive-definitions"/>.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry id="checksum-definition-verify-command">
          <term><literal>verify-command</literal></term>
          <listitem>
            <para>
              Same as
              <xref linkend="checksum-definition-create-command"/>,
              but for checksum verification.
            </para>
          </listitem>
        </varlistentry>

      </variablelist>

      <para>
        Here is a complete example:
        <programlisting>
          [Checksum Definition #1]
          file-patterns=sha1sum.txt
          output-file=sha1sum.txt
          id=sha1sum-gnu
          Name=sha1sum (GNU)
          Name[de]=sha1sum (GNU)
          ...
          create-command=sha1sum -- %f
          verify-command=sha1sum -c -- %f
        </programlisting>
      </para>

    </sect1> <!-- Checksum Definition -->

  </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, 2007, 2008, 2009, 2010 Klar&auml;lvdalens Datakonsult AB</para>

<para>Documentation copyright 2002 &Steffen.Hansen;, copyright 2004
&Daniel.Molkentin;, copyright 2004, 2010 Klar&auml;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:2
sgml-indent-data:t
End:

// vim:ts=2:sw=2:tw=78:noet
-->
