[kde-doc-english] [kleopatra] /: Add kleopatra documentation
Andre Heinecke
aheinecke at intevation.de
Mon Mar 7 11:51:12 UTC 2016
Git commit 9f6554007942295dd0e416c5743fd885eab0e1bb by Andre Heinecke.
Committed on 07/03/2016 at 11:49.
Pushed by aheinecke into branch 'master'.
Add kleopatra documentation
Dependency to doc is optional as online help also may work
for packagers.
M +7 -0 CMakeLists.txt
A +2 -0 doc/CMakeLists.txt
A +3472 -0 doc/index.docbook
http://commits.kde.org/kleopatra/9f6554007942295dd0e416c5743fd885eab0e1bb
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 740f47c..3f1fabc 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -41,6 +41,9 @@ find_package(KF5Notifications ${KF5_VERSION} CONFIG REQUIRED)
find_package(KF5XmlGui ${KF5_VERSION} CONFIG REQUIRED)
find_package(KF5WindowSystem ${KF5_VERSION} CONFIG REQUIRED)
find_package(KF5TextWidgets ${KF5_VERSION} CONFIG REQUIRED)
+find_package(KF5DocTools REQUIRED)
+
+set_package_properties(KF5DocTools PROPERTIES DESCRIPTION "Documentation tools" TYPE OPTIONAL PURPOSE "Required to generate Kleopatra documentation.")
# Kdepimlibs packages
find_package(KF5Libkleo ${LIBKLEO_VERSION} CONFIG REQUIRED)
@@ -115,3 +118,7 @@ if(BUILD_TESTING)
add_subdirectory(tests)
endif()
install( FILES kleopatra.categories DESTINATION ${KDE_INSTALL_CONFDIR} )
+
+if(KF5DocTools_FOUND)
+ add_subdirectory(doc)
+endif()
diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
new file mode 100644
index 0000000..9061c41
--- /dev/null
+++ b/doc/CMakeLists.txt
@@ -0,0 +1,2 @@
+kdoctools_create_handbook(index.docbook INSTALL_DESTINATION ${KDE_INSTALL_DOCBUNDLEDIR}/en SUBDIR kleopatra)
+########### install files ###############
diff --git a/doc/index.docbook b/doc/index.docbook
new file mode 100644
index 0000000..09c9314
--- /dev/null
+++ b/doc/index.docbook
@@ -0,0 +1,3472 @@
+<?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 at 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="http://en.wikipedia.org/wiki/X.509">&x509;</ulink> and <ulink url="http://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="http://en.wikipedia.org/wiki/X.509">&x509;</ulink> and <ulink url="http://en.wikipedia.org/wiki/Pretty_Good_Privacy#OpenPGP">&openpgp;</ulink> certificates in
+ the <ulink url="http://www.gnupg.org/documentation/manuals/gnupg/Invoking-GPGSM.html">&gpgsm;</ulink> and <ulink url="http://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="http://www.gnupg.org/aegypten2/">Ägypten
+Projects</ulink> (Ägypten is German for Egypt). &kleopatra; is the
+German spelling of Cleopatra.</para></note>
+
+</chapter>
+
+<chapter id="functions"><title>Main Functions</title>
+
+<sect1 id="functions-view"><title>Viewing the Local Keybox</title>
+
+<!-- Viewing and Refreshing, also Validation -->
+
+<para>&kleopatra;'s main function is to display and edit the contents
+of the local keybox, which is similar to &gpg;'s concept of keyrings,
+albeit one should not stretch this analogy too much.</para>
+
+<para>The main window is divided into the large key listing area consisting of several tabs, the
+menubar and the <link linkend="functions-search">search bar</link> on
+top, and a status bar at the bottom.</para>
+
+<para>Each line in the key list corresponds to one certificate,
+identified by the so-called <guilabel>Subject &dn;</guilabel>. &dn; is
+an acronym for <quote>Distinguished Name</quote>, a hierarchical
+identifier, much like a file system path with an unusual syntax, that is
+supposed to globally uniquely identify a given certificate.</para>
+
+<para>To be valid, and thus usable, (public) keys need to be signed by
+a &ca; (Certification Authority). These signatures are called
+certificates, but usually the terms <quote>certificate</quote> and
+<quote>(public) key</quote> are used interchangeably, and we will not
+distinguish between them in this manual either, except when explicitly
+noted.</para>
+
+<para>&ca;s must in turn be signed by other &ca;s to be valid. Of
+course, this must end somewhere, so the top-level &ca; (root-&ca;)
+signs its key with itself (this is called a self-signature). Root
+certificates thus need to be assigned validity (commonly called trust)
+manually, ⪚ after comparing the fingerprint with the one on the
+website of the &ca;. This is typically done by the system administrator or
+the vendor of a product using certificates, but can be done by the
+user via &gpgsm;'s command line interface.</para>
+
+<para>To see which of the certificates are root certificates, you
+switch to the hierarchical keylist mode with <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; (⪚ 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 (⪚ 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="http://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 (⪚ 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>Certificate Creation Wizard</guilabel> which will guide you through a
+number of steps to create a certificate request.</para>
+<para>Whenever you are done with a step in
+the wizard, press <guibutton>Next</guibutton> to go to the next step
+(or <guibutton>Back</guibutton> to review steps that are already
+completed). The certificate request creation can be canceled at any
+time by pressing the <guibutton>Cancel</guibutton> button.
+</para>
+<para>On the first page of the wizard choose which type of certificate you want to create:</para>
+
+<variablelist>
+
+<varlistentry>
+<term><guilabel>Create a personal OpenPGP key pair</guilabel></term>
+<listitem><para>&openpgp; key pairs are created locally, and certified by your friends and
+acquaintances. There is no central certification authority; instead, every
+individual creates a personal Web Of Trust by certifying other user's key
+pairs with his own certificate.</para>
+<para>You have to enter a <guilabel>Name</guilabel>, <guilabel>EMail</guilabel> and
+optional a <guilabel>Comment</guilabel>.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Create a personal X.509 key pair and certification request</guilabel></term>
+<listitem>
+<para>&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—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 <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. <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>
+ ⪚ 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 = signer</quote> or <quote>parent
+ = 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—in &openpgp;
+ terms—<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 System</guimenu>
+ <guisubmenu>GPG 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 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 (⪚ 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 (⪚ for signing, signature verification, encryption or
+decryption).</para></warning>
+</listitem>
+</varlistentry>
+-->
+<!--not in 4.2
+varlistentry id="certificates-refresh-crls">
+<term><menuchoice><guimenu>Certificates</guimenu><guimenuitem>Refresh CRLs</guimenuitem></menuchoice></term>
+
+<listitem>
+<para><action>Fetches the current CRLs for all selected keys,</action>
+even though they would normally not be fetched when using the
+key.</para>
+
+<para>This function only has an effect on certificates which define a
+&crl; distribution point. Depending on the backend used, certificates
+configured to perform checks using &ocsp; will not be updated.</para>
+
+<para>You may use this ⪚ if you have sideband knowledge that a key
+has been revoked, and you want the backend to reflect this
+<emphasis>now</emphasis> instead of relying on this to automatically
+happen at the next scheduled &crl; update.</para>
+
+<warning><para>Excessive use of this function might put a high load on
+your provider's or company's network, since CRLs of large
+organizations can be surprisingly big (several megabytes are not
+uncommon).</para>
+
+<para>Use this function scarcely.</para></warning>
+</listitem>
+</varlistentry-->
+
+ <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 Name</replaceable> <optional>(<replaceable>Comment</replaceable>)</optional> <<replaceable>Email</replaceable>></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 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 <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 <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 <!--
+ --><option>-k</option> <!--
+ --><option>--with-validation</option> <!--
+ --><option>--force-crl-refresh</option> <!--
+ --><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/ui.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/ui.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, ⪚ <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 <gpg4winusera at test.hq>
+<!-- -->Key-ID: C6BF6664
+<!-- -->Ownertrust: ultimate<!--
+ --></programlisting>
+ &smime; example:
+ <programlisting><!--
+ -->Subject: CN=Gpg4winTestuserA,OU=Testlab,O=Gpg4win Project,C=DE
+<!-- -->a.k.a.: Gpg4winUserA at 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 (⪚ <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 (⪚) 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 ⪚ 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 (⪚ 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>,
+ ⪚ <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><ALG></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 (⪚ as an
+ <acronym>TLS</acronym> client certificate).
+ </entry>
+ </row>
+ <row>
+ <entry><varname>is-qualified</varname></entry>
+ <entry>boolean</entry>
+ <entry>
+ the key can be used to make Qualified Signatures (as
+ defined by the German Digital Signature Law).
+ </entry>
+ </row>
+ <row>
+ <entry><varname>is-cardkey</varname></entry>
+ <entry>boolean</entry>
+ <entry>
+ the key material is stored on a smartcard (instead of
+ on the computer).
+ </entry>
+ </row>
+ <row>
+ <entry><varname>has-secret-key</varname></entry>
+ <entry>boolean</entry>
+ <entry>
+ the secret key for this key pair is available.
+ </entry>
+ </row>
+ <row>
+ <entry><varname>is-openpgp-key</varname></entry>
+ <entry>boolean</entry>
+ <entry>
+ the key is an &openpgp; key (<literal>true</literal>),
+ or an &smime; key (<literal>false</literal>).
+ </entry>
+ </row>
+ <row>
+ <entry><varname>was-validated</varname></entry>
+ <entry>boolean</entry>
+ <entry>
+ the key has been validated.
+ </entry>
+ </row>
+ <row>
+ <entry><varname><replaceable>prefix</replaceable>-ownertrust</varname></entry>
+ <entry>
+ validity<footnote>
+ <para>
+ Validity is an (ordered) enumeration with the
+ following allowed values:
+ <literal>unknown</literal>,
+ <literal>undefined</literal>,
+ <literal>never</literal>,
+ <literal>marginal</literal>,
+ <literal>full</literal>,
+ <literal>ultimate</literal>. See the &gpg; and
+ &gpgsm; manuals for a detailed explanation.</para>
+ </footnote>
+ </entry>
+ <entry>
+ the key has exactly
+ (<replaceable>prefix</replaceable> = <literal>is</literal>),
+ has anything but
+ (<replaceable>prefix</replaceable> = <literal>is-not</literal>),
+ has at least
+ (<replaceable>prefix</replaceable> = <literal>is-at-least</literal>),
+ or has at most
+ (<replaceable>prefix</replaceable> = <literal>is-at-most</literal>)
+ the ownertrust given as the value of the config key. If
+ more than one
+ <varname><replaceable>prefix</replaceable>-ownertrust</varname>
+ keys (with different
+ <replaceable>prefix</replaceable> values) are present in a
+ single group, the behavior is undefined.
+ </entry>
+ </row>
+ <row>
+ <entry><varname><replaceable>prefix</replaceable>-validity</varname></entry>
+ <entry>validity</entry>
+ <entry>
+ Analogous to
+ <varname><replaceable>prefix</replaceable>-ownertrust</varname>,
+ but for key validity instead of ownertrust.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <note>
+ <para>
+ Some of the more interesting criteria, such as
+ <varname>is-revoked</varname> or
+ <varname>is-expired</varname> will only work on
+ <emphasis>validated</emphasis> keys, which is why, by
+ default, only validated keys are checked for revocation and
+ expiration, although you are free to remove these extra
+ checks.
+ </para>
+ </note>
+
+ <para>
+ In addition to the config keys listed above, a key filter may
+ also have an <varname>id</varname> and
+ <varname>match-contexts</varname>.
+ </para>
+
+ <para>
+ Using the filter's <varname>id</varname>, which defaults to
+ the filter's config group name if not given or empty, you can
+ reference the key filter elsewhere in the configuration, ⪚
+ in &kleopatra;'s View configurations<!--TODO write and
+ link-->. The <varname>id</varname> is not interpreted by
+ &kleopatra;, so you can use any string you like, as long as
+ it's unique.
+ </para>
+
+ <para>
+ The <varname>match-contexts</varname> limits the applicability
+ of the filter. Two contexts are currently defined: The
+ <literal>appearance</literal> context is used when defining
+ coloring and font properties for the views. The
+ <literal>filtering</literal> context is used to selectively
+ include (and exclude) certificate from
+ views. <literal>any</literal> can be used to signify all
+ currently defined contexts, and is the default if
+ <varname>match-contexts</varname> is not given, or otherwise
+ produces no contexts. This ensures that no key filter can end
+ up <quote>dead</quote>, &ie; with no contexts to apply it in.
+ </para>
+
+ <para>
+ The format of the entry is a list of tokens, separated by
+ non-word characters. Each of the tokens is optionally prefixed
+ by an exclamation point (<literal>!</literal>), indicating negation. The tokens act
+ in order on an internal list of contexts, which starts out
+ empty. This is best explained by an example: <literal>any
+ !appearance</literal> is the same as
+ <literal>filtering</literal>, and <literal>appearance
+ !appearance</literal> is producing the empty set, as is
+ <literal>!any</literal>. However, the last two will be
+ internally replaced by <literal>any</literal>, since they
+ produce no contexts at all.
+ </para>
+
+ <para>
+ In general, criteria not specified (&ie; the config entry is
+ not set) are not checked for. If a criterion is given, it
+ is checked for and must match for the filter as a whole to
+ match, &ie; the criteria are AND'ed together.
+ </para>
+
+ <para>
+ Each filter has an implied <quote>specificity</quote> that is
+ used to rank all matching filters. The more specific filter
+ wins over less specific ones. If two filters have the same
+ specificity, the one that comes first in the config file
+ wins. A filter's specificity is proportional to the number of
+ criteria it contains.
+ </para>
+
+ <example>
+ <title>Examples of key filters</title>
+ <para>
+ To check for all expired, but non-revoked root certificates,
+ you would use a key filter defined as follows:
+ </para>
+<!-- isn't there a better way to not indent this in the output??? -->
+ <screen><!--
+-->[Key Filter #<replaceable>n</replaceable>]
+Name=expired, but not revoked
+was-validated=true
+is-expired=true
+is-revoked=false
+is-root-certificate=true
+; ( specificity 4 )<!--
+ --></screen>
+ <para>
+ To check for all disabled &openpgp; keys (not yet supported by &kleopatra;)
+ with ownertrust of at least
+ <quote>marginal</quote>, you would use:
+ </para>
+ <screen><!--
+-->[Key Filter #<replaceable>n</replaceable>]
+Name=disabled OpenPGP keys with marginal or better ownertrust
+is-openpgp=true
+is-disabled=true
+is-at-least-ownertrust=marginal
+; ( specificity 3 )<!--
+ --></screen>
+ </example>
+
+ </sect1>
+
+ <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 Definition #<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 ...</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 ...</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>↦<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
+ ": OK" plus newline in them.
+ </para>
+ </footnote>
+ </para>
+ </note>
+
+ <para>
+ Each checksum program is defined in
+ <filename>libkleopatrarc</filename> as a separate
+ <literal>Checksum Definition #<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älvdalens Datakonsult AB</para>
+
+<para>Documentation copyright 2002 &Steffen.Hansen;, copyright 2004
+&Daniel.Molkentin;, copyright 2004, 2010 Klarälvdalens Datakonsult AB</para>
+
+<itemizedlist>
+<title>Contributors</title>
+<listitem>
+<para>&Marc.Mutz; &Marc.Mutz.mail;</para>
+</listitem>
+<listitem>
+<para>&David.Faure; &David.Faure.mail;</para>
+</listitem>
+<listitem>
+<para>&Steffen.Hansen; <email>hansen at 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
+-->
More information about the kde-doc-english
mailing list