You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1459 lines
54 KiB
1459 lines
54 KiB
<?xml version="1.0" ?>
|
|
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
|
|
<!ENTITY kleopatra "<application>Kleopatra</application>">
|
|
<!ENTITY kwatchgnupg "<application>KWatchGnuPG</application>">
|
|
<!ENTITY gpgsm "<application>GpgSM</application>">
|
|
<!ENTITY gpg "<application>GPG</application>">
|
|
<!ENTITY gpgconf "<application>GpgConf</application>">
|
|
<!ENTITY kappname "&kleopatra;">
|
|
<!ENTITY package "kdepim">
|
|
<!ENTITY smime "<acronym>S/MIME</acronym>">
|
|
<!ENTITY % addindex "IGNORE">
|
|
<!ENTITY % English "INCLUDE">
|
|
|
|
<!ENTITY dn "<acronym>DN</acronym>">
|
|
<!ENTITY ca "<acronym>CA</acronym>">
|
|
|
|
<!-- Expanded all entities to make them translatable - lueck
|
|
FILE menu
|
|
<!ENTITY file-new-key-pair "<menuchoice><guimenu>File</guimenu><guimenuitem>New Key Pair...</guimenuitem></menuchoice>">
|
|
<!ENTITY file-export-certificates "<menuchoice><guimenu>File</guimenu><guimenuitem>Export Certificates...</guimenuitem></menuchoice>">
|
|
<!ENTITY file-export-secret-key "<menuchoice><guimenu>File</guimenu><guimenuitem>Export Secret key...</guimenuitem></menuchoice>">
|
|
<!ENTITY file-import-certificates "<menuchoice><guimenu>File</guimenu><guimenuitem>Import Certificates...</guimenuitem></menuchoice>">
|
|
<!ENTITY file-import-crls "<menuchoice><guimenu>File</guimenu><guimenuitem>Import CRLs...</guimenuitem></menuchoice>">
|
|
<!ENTITY file-quit "<menuchoice><shortcut><keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo></shortcut><guimenu>File</guimenu><guimenuitem>Quit</guimenuitem></menuchoice>">
|
|
|
|
VIEW menu
|
|
<!ENTITY view-redisplay "<menuchoice><shortcut><keycombo action="simul"><keycap>F5</keycap></keycombo></shortcut><guimenu>View</guimenu><guimenuitem>Redisplay</guimenuitem></menuchoice>">
|
|
<!ENTITY view-stop-operation "<menuchoice><shortcut><keycombo action="simul"><keycap>Esc</keycap></keycombo></shortcut><guimenu>View</guimenu><guimenuitem>Stop Operation</guimenuitem></menuchoice>">
|
|
<!ENTITY view-certificate-details "<menuchoice><guimenu>View</guimenu><guimenuitem>Certificate Details...</guimenuitem></menuchoice>">
|
|
<!ENTITY view-hierarchical-key-list "<menuchoice><guimenu>View</guimenu><guimenuitem>Hierarchical Key List</guimenuitem></menuchoice>">
|
|
<!ENTITY view-expand-all "<menuchoice><shortcut><keycombo action="simul">&Ctrl;<keycap>.</keycap></keycombo></shortcut><guimenu>View</guimenu><guimenuitem>Expand All</guimenuitem></menuchoice>">
|
|
<!ENTITY view-collapse-all "<menuchoice><shortcut><keycombo action="simul">&Ctrl;<keycap>,</keycap></keycombo></shortcut><guimenu>View</guimenu><guimenuitem>Collapse All</guimenuitem></menuchoice>">
|
|
|
|
CERTIFICATES menu
|
|
<!ENTITY certificates-validate "<menuchoice><shortcut><keycombo action="simul">&Shift;<keycap>F5</keycap></keycombo></shortcut><guimenu>Certificates</guimenu><guimenuitem>Validate</guimenuitem></menuchoice>">
|
|
<!ENTITY certificates-refresh-crls "<menuchoice><guimenu>Certificates</guimenu><guimenuitem>Refresh CRLs</guimenuitem></menuchoice>">
|
|
<!ENTITY certificates-delete "<menuchoice><shortcut><keycombo action="simul"><keycap>Delete</keycap></keycombo></shortcut><guimenu>Certificates</guimenu><guimenuitem>Delete</guimenuitem></menuchoice>">
|
|
<!ENTITY certificates-download "<menuchoice><guimenu>Certificates</guimenu><guimenuitem>Download</guimenuitem></menuchoice>">
|
|
|
|
CRLS menu
|
|
<!ENTITY crls-clear-crl-cache "<menuchoice><guimenu>CRLs</guimenu><guimenuitem>Clear CRL Cache...</guimenuitem></menuchoice>">
|
|
<!ENTITY crls-dump-crl-cache "<menuchoice><guimenu>CRLs</guimenu><guimenuitem>Dump CRL Cache...</guimenuitem></menuchoice>">
|
|
|
|
TOOLS menu
|
|
<!ENTITY tools-gnupg-log-viewer "<menuchoice><guimenu>Tools</guimenu><guimenuitem>GnuPG Log Viewer...</guimenuitem></menuchoice>">
|
|
|
|
SETTINGS menu
|
|
<!ENTITY settings-show-statusbar "<menuchoice><guimenu>Settings</guimenu><guimenuitem>Show Statusbar</guimenuitem></menuchoice>">
|
|
<!ENTITY settings-configure-shortcuts "<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Shortcuts...</guimenuitem></menuchoice>">
|
|
<!ENTITY settings-configure-kleopatra "<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &kleopatra;...</guimenuitem></menuchoice>">
|
|
<!ENTITY settings-configure-gpgme-backend "<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure GpgME Backend...</guimenuitem></menuchoice>">
|
|
-->
|
|
|
|
<!-- Command line options -->
|
|
<!ENTITY commandline-option-external "<option>--external</option>">
|
|
<!ENTITY commandline-option-query "<option>--query</option>">
|
|
<!ENTITY commandline-option-import-certificate "<option>--import-certificate</option>">
|
|
]>
|
|
|
|
<book lang="&language;">
|
|
|
|
<bookinfo>
|
|
<title>The &kleopatra; Handbook</title>
|
|
|
|
<authorgroup>
|
|
<author>
|
|
<firstname>Marc</firstname>
|
|
<surname>Mutz</surname>
|
|
<affiliation>
|
|
<address><email>marc@klaralvdalens-datakonsult.se</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>2004-06-11</date>
|
|
<releaseinfo>0.31</releaseinfo>
|
|
|
|
<abstract>
|
|
<para>
|
|
&kleopatra; is a tool for managing X.509 certificates.
|
|
</para>
|
|
</abstract>
|
|
|
|
|
|
<keywordset>
|
|
<keyword>KDE</keyword>
|
|
<keyword>Kapp</keyword>
|
|
<keyword>X509</keyword>
|
|
<keyword>LDAP</keyword>
|
|
<keyword>gpg</keyword>
|
|
<keyword>gpgsm</keyword>
|
|
</keywordset>
|
|
|
|
</bookinfo>
|
|
|
|
<chapter id="introduction"> <title>Introduction</title>
|
|
|
|
<para>&kleopatra; is the &kde; tool for managing X.509 certificates in
|
|
the &gpgsm; keybox and for retrieving certificates from
|
|
<acronym>LDAP</acronym> servers.</para>
|
|
|
|
<para>&kleopatra; can be started from &kmail;'s <guimenu>Tools</guimenu>
|
|
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, 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. The name of the &ca; which issued the certificate (its &dn;)
|
|
is shown in the <guilabel>Issuer &dn;</guilabel> column.</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 can
|
|
either compare <guilabel>Subject &dn;</guilabel> and <guilabel>Issuer
|
|
&dn;</guilabel>, or you switch to hierarchical keylist mode with <link
|
|
linkend="view-hierarchical-key-list"><menuchoice><guimenu>View</guimenu>
|
|
<guimenuitem>Hierarchical Key List</guimenuitem></menuchoice></link>.</para>
|
|
|
|
<para>You can see the details of any certificate by double-clicking it
|
|
or using <link linkend="view-certificate-details"><menuchoice><guimenu>View</guimenu>
|
|
<guimenuitem>Certificate Details...</guimenuitem></menuchoice></link>. This opens a
|
|
dialog that shows the most common properties of the certificate, its
|
|
certificate chain (&ie; the chain of issuers up to the root-&ca;), and
|
|
a dump of all information the backend is able to extract from the
|
|
certificate.</para>
|
|
|
|
<para>If you change the keybox without using &kleopatra; (⪚ using
|
|
&gpgsm;'s command line interface), you can refresh the view with <link
|
|
linkend="view-redisplay"><menuchoice><shortcut><keycombo action="simul">
|
|
<keycap>F5</keycap></keycombo></shortcut><guimenu>View</guimenu>
|
|
<guimenuitem>Redisplay</guimenuitem></menuchoice></link>.</para>
|
|
|
|
<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 directory (although &gpgsm; can do
|
|
this automatically), or from a file. You also need to import your own
|
|
certificate after receiving the &ca; answer to your certification
|
|
request.</para>
|
|
|
|
<para>To search for a certificate in an LDAP directory, switch the
|
|
dropdown menu of the search bar from <guilabel>in Local
|
|
Certificates</guilabel> to <guilabel>in External
|
|
Certificates</guilabel>, enter some text (⪚ the name of the person
|
|
you want the certificate for) into the line edit, and click on the
|
|
<guilabel>Find</guilabel> icon. The results will be displayed in the
|
|
key list below the search bar, where you can select certificates to
|
|
either look at them with <link linkend="view-certificate-details">
|
|
<menuchoice><guimenu>View</guimenu><guimenuitem>Certificate Details...</guimenuitem></menuchoice></link> or
|
|
download them with <link linkend="certificates-download">
|
|
<menuchoice><guimenu>Certificates</guimenu><guimenuitem>Download</guimenuitem></menuchoice></link> into the
|
|
local keybox. Note that you can also download the certificate from the
|
|
details dialog, using the <guilabel>Import to Local</guilabel>
|
|
button.</para>
|
|
|
|
<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 <link
|
|
linkend="configuration">configure dialog</link>.</para>
|
|
|
|
<para>If you received the certificate as a file, try <link
|
|
linkend="file-import-certificates"><menuchoice><guimenu>File</guimenu>
|
|
<guimenuitem>Import Certificates...</guimenuitem></menuchoice></link>. &gpgsm; needs to understand the
|
|
format of the certificate file; please refer to &gpgsm;'s manual for a
|
|
list of supported file formats.</para>
|
|
|
|
<para>If you did not <link linkend="functions-newkey">create your
|
|
keypair with &gpgsm;</link>, you also need to manually import the
|
|
public key (as well as the secret key) from the PKCS#12 file you got from
|
|
the &ca;. You can do this on the command line with <link
|
|
linkend="commandline-option-import-certificate"><userinput><command>kleopatra
|
|
&commandline-option-import-certificate;
|
|
<filename>filename</filename></command></userinput></link> or from
|
|
within &kleopatra; with <link
|
|
linkend="file-import-certificates"><menuchoice><guimenu>File</guimenu>
|
|
<guimenuitem>Import Certificates...</guimenuitem></menuchoice></link>,
|
|
just as you would to for <quote>normal</quote> certificates.</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="functions-newkey"><title>Creating New Key Pairs</title>
|
|
|
|
<para>The menu item <link linkend="file-new-key-pair"><menuchoice>
|
|
<guimenu>File</guimenu><guimenuitem>New Key Pair...</guimenuitem></menuchoice></link> starts the
|
|
certificate-request-creating wizard which will guide you through a
|
|
number of steps to create a certificate request; this request can, on the
|
|
last page of the wizard, either be sent to a certificate authority (&ca;)
|
|
to be signed or saved to a file (for example to a floppy, so it can be
|
|
shipped to the &ca;).</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>The first step in the wizard is to type in your personal data
|
|
for the certificate. The fields to fill out are:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><guilabel>Name:</guilabel> Your name;</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><guilabel>Location:</guilabel>The town or city in which you live;</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><guilabel>Organization:</guilabel>The organization you represent
|
|
(for example, the company you work for);</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><guilabel>Department:</guilabel>The organizational unit you are
|
|
in (for example, "Logistics");</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><guilabel>Country code:</guilabel>The two letter code for the
|
|
country in which you are living (for example, "US");</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><guilabel>Email address:</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>
|
|
</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></sect1>
|
|
|
|
|
|
<sect1 id="functions-keybox-management"><title>Keybox Management</title>
|
|
|
|
<para>In addition to <link linkend="functions-view">list and
|
|
validate</link>, <link linkend="functions-search">search and
|
|
import</link> certificates and <link
|
|
linkend="functions-newkey">creating new ones</link>, &kleopatra; also
|
|
has some less often used functions that help you manage your local
|
|
keybox.</para>
|
|
|
|
<para>These functions include deleting certificates from the local
|
|
keybox with <link linkend="certificates-delete"><menuchoice><shortcut>
|
|
<keycombo action="simul"><keycap>Delete</keycap></keycombo></shortcut>
|
|
<guimenu>Certificates</guimenu><guimenuitem>Delete</guimenuitem></menuchoice></link>, as well
|
|
as manual handling of CRLs (<link linkend="certificates-refresh-crls">
|
|
<menuchoice><guimenu>Certificates</guimenu><guimenuitem>Refresh CRLs</guimenuitem>
|
|
</menuchoice></link>, <link linkend="crls-clear-crl-cache"><menuchoice><guimenu>CRLs</guimenu>
|
|
<guimenuitem>Clear CRL Cache...</guimenuitem></menuchoice></link>, <link
|
|
linkend="crls-dump-crl-cache"><menuchoice><guimenu>CRLs</guimenu>
|
|
<guimenuitem>Dump CRL Cache...</guimenuitem></menuchoice></link>).</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><guimenu>File</guimenu><guimenuitem>New Key Pair...</guimenuitem></menuchoice></term>
|
|
|
|
<listitem>
|
|
<para><action>Creates a new key pair (public and private)</action> and
|
|
allows to send the public part to a certification authority
|
|
(&ca;) for signing. The resulting certificate is then
|
|
sent back to you, or stored in an LDAP server for you to download into
|
|
your local keybox, where you can use it to sign and decrypt
|
|
mails.</para>
|
|
|
|
<para>This mode of operation is called <quote>decentralized key
|
|
generation</quote>, since all keys are created locally. &kleopatra;
|
|
(and &gpgsm;) do not support <quote>centralized key generation</quote>
|
|
directly, but you can import the public/secret key bundle that you
|
|
receive from the &ca; in PKCS#12 format via <menuchoice><guimenu>File</guimenu>
|
|
<guimenuitem>Import Certificates...</guimenuitem></menuchoice>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
|
|
<varlistentry id="file-export-certificates">
|
|
<term><menuchoice><guimenu>File</guimenu><guimenuitem>Export Certificates...</guimenuitem></menuchoice></term>
|
|
|
|
<listitem>
|
|
<para><action>Exports the selected certificates</action> into a file.</para>
|
|
|
|
<note><para>This exports only the public keys, even if the
|
|
secret key is available. Use <menuchoice><guimenu>File</guimenu><guimenuitem>Export
|
|
Secret key...</guimenuitem></menuchoice> to export both
|
|
public and secret keys into a file, but note that this is almost
|
|
always a bad idea.</para></note>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
|
|
<varlistentry id="file-export-secret-key">
|
|
<term><menuchoice><guimenu>File</guimenu><guimenuitem>Export Secret key...</guimenuitem></menuchoice></term>
|
|
|
|
<listitem>
|
|
<para><action>Exports both the public and the secret key to a
|
|
(PKCS#12) file.</action></para>
|
|
|
|
<warning><para>It should rarely be necessary to use this function, and
|
|
if it is, it should be carefully planned. Planning the migration of a
|
|
secret key involves choice of transport media and secure deletion of
|
|
the key data on the old machine, as well as the transport medium,
|
|
among other things.</para></warning>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
|
|
<varlistentry id="file-import-certificates">
|
|
<term><menuchoice><guimenu>File</guimenu><guimenuitem>Import Certificates...</guimenuitem></menuchoice></term>
|
|
|
|
<listitem>
|
|
<para><action>Imports certificates and/or secret keys from files into
|
|
the local keybox.</action></para>
|
|
|
|
<para>The format of the certificate file must be supported by
|
|
&gpgsm;. Please refer to the &gpgsm; manual for a list of supported
|
|
formats.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
|
|
<varlistentry id="file-import-crls">
|
|
<term><menuchoice><guimenu>File</guimenu><guimenuitem>Import CRLs...</guimenuitem></menuchoice></term>
|
|
|
|
<listitem>
|
|
<para><action>Lets you manually import CRLs from
|
|
files.</action></para>
|
|
|
|
<para>Normally, Certificate Revocation Lists (CRLs) are handled
|
|
transparently by the backend, but it can sometimes be useful to
|
|
import a CRL manually into the local CRL cache.</para>
|
|
|
|
<note><para>For CRL import to work, the
|
|
<application>dirmngr</application> tool must be in the search
|
|
<varname>PATH</varname>. If this menu item is disabled, you should
|
|
contact the system administrator and ask them to install
|
|
<application>dirmngr</application>.</para></note>
|
|
|
|
<para>You can view the contents of the local CRL cache from the menu
|
|
item <menuchoice><guimenu>CRLs</guimenu><guimenuitem>Dump CRL Cache...</guimenuitem>
|
|
</menuchoice>. This will display a dialog with
|
|
information about the CRLs in the cache and the fingerprints of the
|
|
certificates in each CRL.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
|
|
<varlistentry id="file-quit">
|
|
<term><menuchoice><shortcut><keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo></shortcut>
|
|
<guimenu>File</guimenu><guimenuitem>Quit</guimenuitem></menuchoice></term>
|
|
|
|
<listitem>
|
|
<para><action>Terminates &kleopatra;.</action></para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</sect1> <!-- File Menu -->
|
|
|
|
|
|
|
|
<sect1 id="menuview"><title>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>Redisplays the selected certificates or refreshes the
|
|
certificate list.</action></para>
|
|
|
|
<para>If there are selected certificates, the refresh operation is
|
|
restricted to those selected entries.</para>
|
|
|
|
<para>If a query result (either remote or local) is currently
|
|
displayed, the query is re-issued and the new results are displayed in
|
|
place of the old ones.</para>
|
|
|
|
<para>If no query has been performed, the whole keybox contents is
|
|
re-fetched and re-displayed.</para>
|
|
|
|
<para>You can use this if you have changed the contents of
|
|
the keybox by other means than &kleopatra; (⪚ by using &gpgsm;'s
|
|
command line interface).</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
|
|
<varlistentry id="view-stop-operation">
|
|
<term><menuchoice><shortcut><keycombo action="simul">&Esc;</keycombo></shortcut>
|
|
<guimenu>View</guimenu><guimenuitem>Stop Operation</guimenuitem></menuchoice></term>
|
|
|
|
<listitem>
|
|
<para><action>Stops (cancels) all pending operations,</action> ⪚ a
|
|
search or a download.</para>
|
|
|
|
<note><para>Depending on the server used, cancelling a remote search
|
|
can block &kleopatra; for a few seconds while waiting for the backend
|
|
to complete the procedure. This is normal and expected
|
|
behavior.</para></note>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
|
|
<varlistentry id="view-certificate-details">
|
|
<term><menuchoice><guimenu>View</guimenu><guimenuitem>Certificate Details...</guimenuitem></menuchoice></term>
|
|
|
|
<listitem>
|
|
<para><action>Shows the details of the currently selected
|
|
certificate.</action></para>
|
|
|
|
<para>This function is also available by double-clicking the
|
|
corresponding item in the list view directly.</para>
|
|
|
|
<!--FIXME: link to the dialog's help, but where do we put _that_?-->
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
|
|
<varlistentry id="view-hierarchical-key-list">
|
|
<term><menuchoice><guimenu>View</guimenu><guimenuitem>Hierarchical Key List</guimenuitem></menuchoice></term>
|
|
|
|
<listitem>
|
|
<para><action> Toggles between hierarchical and flat keylist mode.
|
|
</action></para>
|
|
|
|
<para>In hierarchical mode, certificates are arranged in
|
|
issuer/subject relation, so it is easy to see to which certification
|
|
hierarchy a given certificate belongs, but a given certificate is
|
|
harder to find initially (though you can of course use the
|
|
<link linkend="functions-search">search bar</link>).</para>
|
|
|
|
<para>In flat mode, all certificates are displayed in a flat list,
|
|
sorted alphabetically. In this mode, a given certificate is easy to
|
|
find, but it is not directly clear which root certificate it belongs
|
|
to.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
|
|
<varlistentry id="view-expand-all">
|
|
<term><menuchoice><shortcut><keycombo action="simul">&Ctrl;<keycap>.</keycap>
|
|
</keycombo></shortcut><guimenu>View</guimenu><guimenuitem>Expand All</guimenuitem></menuchoice></term>
|
|
|
|
<listitem>
|
|
<para>(This function is only available when <link
|
|
linkend="view-hierarchical-key-list"><menuchoice><guimenu>View</guimenu>
|
|
<guimenuitem>Hierarchical Key List</guimenuitem></menuchoice></link> is on.)</para>
|
|
|
|
<para><action>Expands all list items in the certificate list
|
|
view,</action> &ie; makes all items visible.</para>
|
|
|
|
<para>This is the default when entering hierarchical keylist
|
|
mode.</para>
|
|
|
|
<para>You can still expand and collapse each individual item by
|
|
itself, of course.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry id="view-collapse-all">
|
|
<term><menuchoice><shortcut><keycombo action="simul">&Ctrl;<keycap>,</keycap>
|
|
</keycombo></shortcut><guimenu>View</guimenu><guimenuitem>Collapse All</guimenuitem></menuchoice></term>
|
|
|
|
<listitem>
|
|
<para>(This function is only available when <link
|
|
linkend="view-hierarchical-key-list"><menuchoice><guimenu>View</guimenu>
|
|
<guimenuitem>Hierarchical Key List</guimenuitem></menuchoice></link> is on.)</para>
|
|
|
|
<para><action>Collapses all list items in the certificate list
|
|
view,</action> &ie; hides all but the top-level items.</para>
|
|
|
|
<para>You can still expand and collapse each individual item by
|
|
itself, of course.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="menucertificates"><title>Certificates Menu</title>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry id="certificates-validate">
|
|
<term><menuchoice><shortcut><keycombo action="simul">&Shift;<keycap>F5</keycap></keycombo>
|
|
</shortcut><guimenu>Certificates</guimenu><guimenuitem>Validate</guimenuitem></menuchoice></term>
|
|
|
|
<listitem>
|
|
<para><action>Validates selected (or all) keys.</action></para>
|
|
|
|
<para>This is similar to <link
|
|
linkend="view-redisplay"><menuchoice><shortcut><keycombo action="simul">
|
|
<keycap>F5</keycap></keycombo></shortcut><guimenu>View</guimenu>
|
|
<guimenuitem>Redisplay</guimenuitem></menuchoice></link>, but
|
|
performs a validation of the (selected) keys. Validation here means
|
|
that all relevant CRLs are fetched, and the certificate chain is
|
|
checked for correctness. As a result, invalid or expired keys will be
|
|
marked according to your color and font preferences set in the <link
|
|
linkend="configuration-appearance"><guilabel>Appearance</guilabel>
|
|
page</link> of &kleopatra;'s <link linkend="configuration">configure
|
|
dialog</link>.</para>
|
|
|
|
<warning><para>You can only rely on information from validated keys,
|
|
and, since any of them may be revoked at any time, even validation is
|
|
only ever a snapshot of the current state of the local keyring. This
|
|
is why the backend normally performs such checks whenever the keys
|
|
are used (⪚ for signing, signature verification, encryption or
|
|
decryption).</para></warning>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<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 id="certificates-delete">
|
|
<term><menuchoice><shortcut><keycombo action="simul"><keycap>Delete</keycap></keycombo></shortcut>
|
|
<guimenu>Certificates</guimenu><guimenuitem>Delete</guimenuitem></menuchoice></term>
|
|
|
|
<listitem>
|
|
<para><action>Deletes selected certificate(s)</action> from the local keyring.</para>
|
|
|
|
<para>Use this function to remove unused keys from your local
|
|
keybox. However, since certificates are typically attached to signed
|
|
emails, verifying an email might result in the key just removed to pop
|
|
back into the local keybox. So it is probably best to avoid using this
|
|
function as much as possible. When you are lost, use the <link
|
|
linkend="functions-search">search bar</link> or the <link
|
|
linkend="view-hierarchical-key-list"><menuchoice><guimenu>View</guimenu>
|
|
<guimenuitem>Hierarchical Key List</guimenuitem></menuchoice></link> function to regain control over
|
|
the lot of certificates.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry 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="menucrls"><title>CRLs Menu</title>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry id="crls-clear-crl-cache">
|
|
<term><menuchoice><guimenu>CRLs</guimenu><guimenuitem>Clear CRL Cache...</guimenuitem></menuchoice></term>
|
|
|
|
<listitem>
|
|
<para><action>Clears the &gpgsm; CRL cache.</action></para>
|
|
|
|
<para>You probably never need this. You can force a refresh of the CRL
|
|
cache by selecting all certificates and using <link linkend="certificates-refresh-crls"><menuchoice>
|
|
<guimenu>Certificates</guimenu><guimenuitem>Refresh CRLs</guimenuitem></menuchoice></link> instead.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="crls-dump-crl-cache">
|
|
<term><menuchoice><guimenu>CRLs</guimenu><guimenuitem>Dump CRL Cache...</guimenuitem></menuchoice></term>
|
|
|
|
<listitem>
|
|
<para><action>Shows the detailed contents of the &gpgsm; CRL
|
|
cache.</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></para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="menusettings"><title>Settings Menu</title>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry id="settings-show-statusbar">
|
|
<term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Show Statusbar</guimenuitem></menuchoice></term>
|
|
|
|
<listitem>
|
|
<para><action>Toggles the visibility of the bottom status bar.</action></para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="settings-configure-shortcuts">
|
|
<term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Shortcuts...</guimenuitem></menuchoice></term>
|
|
|
|
<listitem>
|
|
<para><action>Opens the standard &kde; shortcut configuration dialog,
|
|
where you can assign and re-assign keyboard shortcuts for all menu
|
|
items.</action></para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="settings-configure-kleopatra">
|
|
<term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &kleopatra;...</guimenuitem></menuchoice></term>
|
|
|
|
<listitem>
|
|
<para><action>Opens &kleopatra;'s configure dialog.</action></para>
|
|
|
|
<para>See <xref linkend="configuration"/> for more details.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="settings-configure-gpgme-backend">
|
|
<term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure GpgME 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="menuhelp"><title>Help Menu</title>
|
|
|
|
|
|
<para>The <guimenu>Help</guimenu> menu contains the standard &kde;
|
|
help menu.</para>
|
|
|
|
&help.menu.documentation;
|
|
|
|
</sect1>
|
|
|
|
</chapter>
|
|
|
|
<chapter id="commandline-options"><title>Command Line Options Reference</title>
|
|
|
|
<para>Only the options specific to &kleopatra; are listed here. As
|
|
with all &kde; applications, you can get a complete list of options
|
|
by issuing the command <userinput><command>kleopatra
|
|
<option>--help</option></command></userinput>.</para>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry id="commandline-option-external">
|
|
<term>&commandline-option-external;</term>
|
|
|
|
<listitem>
|
|
<para><action>Specifies that &commandline-option-query; shall search
|
|
remotely instead of in the local keybox.</action></para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="commandline-option-query">
|
|
<term>&commandline-option-query;</term>
|
|
|
|
<listitem>
|
|
<para><action>Specifies that &kleopatra; shall start with the given
|
|
query string instead of listing the complete local
|
|
keybox.</action></para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="commandline-option-import-certificate">
|
|
<term>&commandline-option-import-certificate;</term>
|
|
|
|
<listitem>
|
|
<para><action>Specifies a file or URL from which to import
|
|
certificates (or secret keys) from.</action></para>
|
|
|
|
<para>This is the command line equivalent of <link
|
|
linkend="file-import-certificates"><menuchoice><guimenu>File</guimenu>
|
|
<guimenuitem>Import Certificates...</guimenuitem></menuchoice></link>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</chapter>
|
|
|
|
<chapter id="configuration"><title>Configuring &kleopatra;</title>
|
|
|
|
<para>&kleopatra;'s configure dialog can be accessed via <link
|
|
linkend="settings-configure-kleopatra"><menuchoice><guimenu>Settings</guimenu>
|
|
<guimenuitem>Configure &kleopatra;...</guimenuitem></menuchoice></link>.</para>
|
|
|
|
<para>Each of its pages is described in the sections below.</para>
|
|
|
|
<sect1 id="configuration-directory-services"><title>Configuring Directory Services</title>
|
|
|
|
<para>On this page, you can configure which LDAP servers to use for
|
|
certificate searches. You can also configure their order, as well as
|
|
some selected LDAP-related settings from the dynamic backend
|
|
configuration dialog, available via <link
|
|
linkend="settings-configure-gpgme-backend"><menuchoice><guimenu>Settings</guimenu>
|
|
<guimenuitem>Configure GpgME Backend...</guimenuitem></menuchoice></link>.</para>
|
|
|
|
<para>To add a new server, click on the <guilabel>Add
|
|
Service...</guilabel> button. In the dialog that appears, you can set
|
|
the <guilabel>Server name</guilabel>, the <guilabel>Port</guilabel>
|
|
(preset to the default LDAP port), the <guilabel>Base &dn;</guilabel>
|
|
(sometimes referred to as the search root or search base), and the
|
|
usual <guilabel>User name</guilabel> and
|
|
<guilabel>Password</guilabel>, both of which are only needed if the
|
|
server requires authentication. Clicking <guilabel>OK</guilabel> adds
|
|
the server details to the list of servers, while
|
|
<guilabel>Cancel</guilabel> dismisses the input.</para>
|
|
|
|
<para>To remove a server from the search list, select it in the list,
|
|
then press the <guilabel>Remove Service</guilabel> button.</para>
|
|
|
|
<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
|
|
labelled <guilabel>LDAP timeout</guilabel>.</para>
|
|
|
|
<para>If one of your servers has a large database, so that even
|
|
reasonable searches like <userinput>Smith</userinput> hit the
|
|
<guilabel>maximum number of items returned by query</guilabel>, you
|
|
might want to increase this limit. You can find out easily if you hit
|
|
the limit during a search, since a dialog box will pop up in that
|
|
case, telling you that the results have been truncated.</para>
|
|
|
|
<note><para>Some servers may impose their own limits on the number of
|
|
items returned from a query. In this case, increasing the limit here
|
|
will not result in more returned items.</para></note>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="configuration-appearance"><title>Configuring Visual Appearance</title>
|
|
|
|
<para>&kleopatra; allows you to customize the appearance of
|
|
(validated) keys in the list view. This includes the foreground (text)
|
|
and background colors, as well as the font.</para>
|
|
|
|
<para>Each <guilabel>Key Category</guilabel> on the left is assigned a
|
|
set of colors and a font in which keys belonging to that category are
|
|
displayed. The category list also acts as a preview of the
|
|
settings. Categories can be freely defined by the administrator or the
|
|
power user, see <xref linkend="admin-key-filters"/> in <xref
|
|
linkend="admin"/>.</para>
|
|
|
|
<para>To change the text (foreground) color of a category, select it
|
|
in the list, and press the <guilabel>Set Text Color...</guilabel>
|
|
button. The standard &kde; color selection dialog will appear where
|
|
you can select or create a new color.</para>
|
|
|
|
<para>Changing the background color is done in the same way, just press
|
|
<guilabel>Set Background Color...</guilabel> instead.</para>
|
|
|
|
<para>To change the font, you basically have two options:</para>
|
|
|
|
<orderedlist>
|
|
<listitem><para>Modify the standard font, used for all list views in
|
|
&kde;</para></listitem>
|
|
<listitem><para>Use a custom font.</para></listitem>
|
|
</orderedlist>
|
|
|
|
<para>The first option has the advantage that the font will follow
|
|
whichever style you choose &kde;-wide, whereas the latter gives you
|
|
full control over the font to use. The choice is yours.</para>
|
|
|
|
<para>To use the modified standard font, select the category in the
|
|
list, and check or uncheck the font modifiers
|
|
<guilabel>Italic</guilabel>, <guilabel>Bold</guilabel>, and/or
|
|
<guilabel>Strikeout</guilabel>. You can immediately see the effect on
|
|
the font in the category list.</para>
|
|
|
|
<para>To use a custom font, press the <guilabel>Set Font...</guilabel>
|
|
button. The standard &kde; font selection dialog will appear where you
|
|
can select the new font. Note that you can still use the font
|
|
modifiers to change the custom font, just as for modifying the
|
|
standard font.</para>
|
|
|
|
<para>To switch back to the standard font, you need to press the
|
|
<guilabel>Default Appearance</guilabel> button.</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="configuration-dn-order"><title>Configuring the Order &dn; Attributes are Shown</title>
|
|
|
|
<para>Although &dn;s are hierarchical, the order of the individual
|
|
components (called relative &dn;s (RDNs), or &dn; attributes) is not
|
|
defined. The order in which the attributes are shown is thus a matter
|
|
of personal taste or company policy, which is why it is configurable in
|
|
&kleopatra;.</para>
|
|
|
|
<note><para>This setting does not only apply to &kleopatra;, but to all
|
|
applications using &kleopatra; Technology. At the time of this
|
|
writing, these include &kmail;, &kaddressbook;, as well as &kleopatra;
|
|
itself, of course.</para></note>
|
|
|
|
<para>This configuration page basically consists of two lists, one for
|
|
the known attributes (<guilabel>Available attributes</guilabel>), and
|
|
one describing the <guilabel>Current attribute order</guilabel>.</para>
|
|
|
|
<para>Both lists contain entries described by the short from of the
|
|
attribute (⪚ <guilabel>CN</guilabel>) as well as the spelled-out
|
|
form (<guilabel>Common Name</guilabel>).</para>
|
|
|
|
<para>The <guilabel>Available attributes</guilabel> list is always
|
|
sorted alphabetically, while the <guilabel>Current attribute
|
|
order</guilabel> list's order reflects the configured &dn; attribute
|
|
order: the first attribute in the list is also the one displayed
|
|
first.</para>
|
|
|
|
<para>Only attributes explicitly listed in the <guilabel>Current
|
|
attribute order</guilabel> list are displayed at all. The rest is
|
|
hidden by default.</para>
|
|
|
|
<para>However, if the placeholder entry <guilabel>_X_</guilabel>
|
|
(<guilabel>All others</guilabel>) is in the <quote>current</quote>
|
|
list, all unlisted attributes (whether known or not), are inserted at
|
|
the point of <guilabel>_X_</guilabel>, in their original relative
|
|
order.</para>
|
|
|
|
<para>A small example will help to make this more clear:</para>
|
|
|
|
<informalexample>
|
|
<para>Given the &dn;</para>
|
|
<blockquote>
|
|
<para>
|
|
O=KDE, C=US, CN=Dave Devel, X-BAR=foo, OU=Kleopatra, X-FOO=bar,
|
|
</para>
|
|
</blockquote>
|
|
<para>the default attribute order of <quote>CN, L, _X_, OU, O,
|
|
C</quote> will produce the following formatted &dn;:</para>
|
|
<blockquote>
|
|
<para>
|
|
CN=Dave Devel, X-BAR=foo, X-FOO=bar, OU=Kleopatra, O=KDE, C=US
|
|
</para>
|
|
</blockquote>
|
|
<para>while <quote>CN, L, OU, O, C</quote> will produce</para>
|
|
<blockquote>
|
|
<para>
|
|
CN=Dave Devel, OU=Kleopatra, O=KDE, C=US
|
|
</para>
|
|
</blockquote>
|
|
</informalexample>
|
|
|
|
<para>To add an attribute to the display order list, select it in the
|
|
<guilabel>Available attributes</guilabel> list, and press the
|
|
<guilabel>Add to current attribute order</guilabel> button.</para>
|
|
|
|
<para>To remove an attribute from the display order list, select it in
|
|
the <guilabel>Current attribute order</guilabel> list, and press the
|
|
<guilabel>Remove from current attribute order</guilabel> button.</para>
|
|
|
|
<para>To move an attribute to the beginning (end), select it in the
|
|
<guilabel>Current attribute order</guilabel> list, and press the
|
|
<guilabel>Move to top</guilabel> (<guilabel>Move to bottom</guilabel>)
|
|
button.</para>
|
|
|
|
<para>To move an attribute up (down) one slot only, select it in the
|
|
<guilabel>Current attribute order</guilabel> list, and press the
|
|
<guilabel>Move one up</guilabel> (<guilabel>Move one down</guilabel>)
|
|
button.</para>
|
|
|
|
</sect1>
|
|
|
|
</chapter>
|
|
|
|
<chapter id="admin"><title>Administrator's Guide</title>
|
|
|
|
<para>This Administrator's Guide describes ways to customize &kleopatra; that
|
|
are not accessible via the &GUI;, but only via config files.</para>
|
|
|
|
<para>It is assumed that the reader is familiar with the technology
|
|
used for &kde; application configuration, including layout,
|
|
file system location and cascading of &kde; config files, as well as
|
|
the KIOSK framework.</para>
|
|
|
|
<sect1 id="admin-certificate-request-wizard"><title>Customization of the Certificate-Creation Wizard</title>
|
|
|
|
<para>&kleopatra; allows you to customize the fields that the user is
|
|
allowed to enter in order to create their certificate.</para>
|
|
|
|
<para>Create a group called
|
|
<literal>CertificateCreationWizard</literal> in the system-wide
|
|
<filename>kleopatrarc</filename>. If you want a custom order of
|
|
attributes or if you only want certain items to appear, create a key
|
|
called <varname>DNAttributeOrder</varname>. The argument is one or
|
|
more of <varname>CN,SN,GN,L,T,OU,O,PC,C,SP,DC,BC,EMAIL</varname> If
|
|
you want to initialize fields with a certain value, write something like
|
|
Attribute=value. If you want the attribute to be treated as a required
|
|
one, append an exclamation mark
|
|
(e.g. <varname>CN!,L,OU,O!,C!,EMAIL!</varname>, which happens to be
|
|
the default configuration).</para>
|
|
|
|
<para> Using the <acronym>KIOSK</acronym> mode modifier
|
|
<varname>$e</varname> allows to retrieve the values from
|
|
environment variables or from an evaluated script or binary. If you
|
|
want to disallow editing of the respective field in addition, use the
|
|
modifier <varname>$i</varname>. If you want to disallow the use
|
|
<guibutton>Insert My Address</guibutton> button, set
|
|
<varname>ShowSetWhoAmI</varname> to false.</para>
|
|
|
|
<tip><para> Due to the nature of the &kde; <acronym>KIOSK</acronym>
|
|
framework, using the immutable flag (<varname>$i</varname>) makes it
|
|
impossible for the user to override the flag. This is intended
|
|
behavior. <varname>$i</varname> and <varname>$e</varname> can be used
|
|
with all other config keys in &kde; applications as well.</para></tip>
|
|
|
|
<para>The following example outlines possible customizations:</para>
|
|
|
|
<para>
|
|
<programlisting>
|
|
[CertificateCreationWizard]
|
|
;Disallow to copy personal data from the addressbook, do not allow local override
|
|
ShowSetWhoAmI[$i]=false
|
|
|
|
;sets the user name to $USER
|
|
CN[$e]=$USER
|
|
|
|
;sets the company name to "My Company", disallows editing
|
|
O[$i]=My Company
|
|
|
|
;sets the department name to a value returned by a script
|
|
OU[$ei]=$(lookup_dept_from_ip)
|
|
|
|
; sets country to DE, but allows for changes by the user
|
|
C=DE
|
|
</programlisting>
|
|
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="admin-key-filters">
|
|
|
|
<title>
|
|
Creating and Editing Key Categories
|
|
</title>
|
|
|
|
<para>
|
|
&kleopatra; allows the user to configure the <link
|
|
linkend="configuration-appearance">visual appearance</link> of
|
|
keys based on a concept called <guilabel>Key
|
|
Categories</guilabel>. 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.
|
|
</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 key in a <literal>Key Filter
|
|
#<replaceable>n</replaceable></literal> group is
|
|
<varname>Name</varname>, containing the name of the category
|
|
as displayed in the <link
|
|
linkend="configuration-appearance">config dialog</link>.
|
|
</para>
|
|
|
|
<para>
|
|
<xref linkend="table-key-filters-appearance"/> lists all keys
|
|
that define the display properties of keys belonging to that
|
|
category (&ie; those keys that can be adjusted in the <link
|
|
linkend="configuration-appearance">config dialog</link>),
|
|
whereas <xref linkend="table-key-filters-criteria"/> lists all
|
|
keys that define the criteria the filter matches keys against.
|
|
</para>
|
|
|
|
<table id="table-key-filters-appearance">
|
|
<title>Key-Filter Configuration Keys Defining Display
|
|
Properties</title>
|
|
<tgroup cols="3">
|
|
<colspec colnum="2" align="center"/>
|
|
<thead>
|
|
<row>
|
|
<entry>Config Key</entry>
|
|
<entry>Type</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<!--tfoot/-->
|
|
<tbody>
|
|
<row>
|
|
<entry><varname>background-color</varname></entry>
|
|
<entry>color</entry>
|
|
<entry>
|
|
The background color to use. If missing, defaults to
|
|
whichever background color is defined globally for list
|
|
views.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>foreground-color</varname></entry>
|
|
<entry>color</entry>
|
|
<entry>
|
|
The foreground color to use. If missing, defaults to
|
|
whichever foreground color is defined globally for list
|
|
views.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>font</varname></entry>
|
|
<entry>font</entry>
|
|
<entry>
|
|
The custom font to use. The font will be scaled to the
|
|
size configured for list views, and any font
|
|
attributes (see below) will be applied.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>font-bold</varname></entry>
|
|
<entry>boolean</entry>
|
|
<entry>
|
|
If set to <literal>true</literal> and
|
|
<varname>font</varname> is not set, uses the
|
|
default list view font with bold font style added (if
|
|
available). Ignored if <varname>font</varname> is also
|
|
present.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>font-italic</varname></entry>
|
|
<entry>boolean</entry>
|
|
<entry>
|
|
Analogous to <varname>font-bold</varname>, but for
|
|
italic font style instead of bold.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>font-strikeout</varname></entry>
|
|
<entry>boolean</entry>
|
|
<entry>
|
|
If <literal>true</literal>, draws a centered line over
|
|
the font. Applied even if
|
|
<varname>font</varname> is set.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>icon</varname></entry>
|
|
<entry>text</entry>
|
|
<entry>
|
|
The name of an icon to show in the first column. Not yet
|
|
implemented.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
|
|
<table id="table-key-filters-criteria">
|
|
<title>Key-Filter Configuration Keys Defining Filter Criteria</title>
|
|
<tgroup cols="3">
|
|
<colspec colnum="2" align="center"/>
|
|
<thead>
|
|
<row>
|
|
<entry>Config Key</entry>
|
|
<entry>Type</entry>
|
|
<entry>If specified, filter matches when...</entry>
|
|
</row>
|
|
</thead>
|
|
<!--tfoot/-->
|
|
<tbody>
|
|
<row>
|
|
<entry><varname>is-revoked</varname></entry>
|
|
<entry>boolean</entry>
|
|
<entry>the key has been revoked.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>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>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 (see <link
|
|
linkend="certificates-validate"><menuchoice><shortcut><keycombo action="simul">&Shift;<keycap>F5</keycap></keycombo></shortcut>
|
|
<guimenu>Certificates</guimenu><guimenuitem>Validate</guimenuitem></menuchoice></link>).
|
|
</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 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>
|
|
|
|
<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<!--
|
|
--></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<!--
|
|
--></screen>
|
|
</example>
|
|
|
|
</sect1>
|
|
|
|
</chapter> <!-- Administrator's Guide -->
|
|
|
|
<chapter id="credits-and-license">
|
|
<title>Credits and License</title>
|
|
|
|
<para>&kleopatra; copyright 2002 &Steffen.Hansen;, &Matthias.Kalle.Dalheimer;
|
|
and &Jesper.Pedersen;., copyright 2004 &Daniel.Molkentin;, copyright 2004 Klarälvdalens Datakonsult AB</para>
|
|
|
|
<para>Documentation copyright 2002 &Steffen.Hansen;, copyright 2004
|
|
&Daniel.Molkentin;, copyright 2004 Klarälvdalens Datakonsult AB</para>
|
|
|
|
<itemizedlist>
|
|
<title>Contributors</title>
|
|
<listitem>
|
|
<para>&Marc.Mutz; &Marc.Mutz.mail;</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>&David.Faure; &David.Faure.mail;</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>&Steffen.Hansen; <email>hansen@kde.org</email></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>&Matthias.Kalle.Dalheimer; &Matthias.Kalle.Dalheimer.mail;</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>&Jesper.Pedersen; &Jesper.Pedersen.mail;</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>&Daniel.Molkentin; &Daniel.Molkentin.mail;</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
|
|
&underFDL;
|
|
&underGPL;
|
|
</chapter>
|
|
|
|
&documentation.index;
|
|
</book>
|
|
|
|
<!--
|
|
Local Variables:
|
|
mode: sgml
|
|
sgml-minimize-attributes:nil
|
|
sgml-general-insert-case:lower
|
|
sgml-indent-step:0
|
|
sgml-indent-data:nil
|
|
End:
|
|
|
|
// vim:ts=2:sw=2:tw=78:noet
|
|
-->
|