xca/doc/xca.sgml

<!doctype linuxdoc system>


<article>

<title>XCA <!-- insert your title here -->
<author>Christian Hohnstädt, <tt/christian@hohnstaedt.de/ <!-- insert your name here -->
<date>$Date$            <!-- always have a version number and a date -->
<abstract>                          <!-- the abstract: a short and precise description -->
<nidx>(your index root)</nidx>    <!-- add indexing keywords as you go along -->
                         <!-- nidx means the indexed word is not in output of main text, only in the index -->

This application is intended for creating and managing X.509 certificates
and RSA keys (DSA keys maybe supported in a later release
since they are not wideley used in PKI cryptography).
Everything that is needed for a CA is implemented.
All CAs can sign sub-CAs rekursively. These certificate chains are shown clearly in a list-view.
For an easy company-wide use there are customiseable templates that can be used for certificate or request generation.
All crypto data is stored in a local Berkeley database. 
</abstract>



<!-- Table of contents -->
<toc>

<!-- Begin the document -->


<sect>Introduction

<p>
<nidx>(your index root)!introduction</nidx>   <!-- here introduction is a sub entry of template, exclamationmark is separator -->
This application is intended as Certificate and Keystore and as 
signing application issuing certificates.

<p>
All datastructures (Keys, Certificate signing requests, Certificates and Templates) can be imported
and exported in several formats like DER or PEM.
Import means reading a file from the filesystem and storing the datastructure
into the databasefile, while exporting means to write the datastructure
from the databasefile to the filesystem to be e.g imported to an other application.

<p>
When starting the application the first time, it needs a password to encrypt the
private keys in the database.
After starting the application all RSA keys are hold <bf>unencrypted</bf> in the RAM of the computer.
This is a security issue to be aware of.

<p>
The different parts are divided over 4 Tabs: Keys, Requests, Certificates and Templates.
All items can be manipulated either by a context menu available by
right-clicking on the item, or by using the buttons at the right border.
Every item gets an internal name which is unique in one tab-view and is
always shown in the first column.

<sect1>File formats
<p>
There are several default file-formats to exchange cryptographic the data with
other applications.
<itemize>
<item><bf>DER</bf> <bf>D</bf>istinguished <bf>E</bf>ncoding <bf>R</bf>ules is the binary ASN.1 encoding of the data.
<item><bf>PEM</bf> <bf>P</bf>rivacy-<bf>E</bf>nhanced <bf>M</bf>ail is the base64 encoded version of the 
	<bf>DER</bf> formatted data with additional header and footer lines to be transported via e.g. E-mail
<item><bf>PKCS&num;X</bf> <bf>P</bf>ublic <bf>K</bf>ey <bf>C</bf>ryptography <bf>S</bf>tandards 
	published by <url url="http://www.rsasecurity.com" name="RSA Laboratories">
	
</itemize>

<sect1>Further reading <label id="otherdoc">
<p>
<enum>
<item><url url="http://tldp.org/HOWTO/SSL-Certificates-HOWTO/" name="SSL Certificates HOWTO">
<item><url url="http://ospkibook.sourceforge.net/" name="OS-PKI book">
</enum>

<sect1>Copyright
<p>
<tscreen><verb>
/*
 * Copyright (C) 2001 Christian Hohnstaedt.
 *
 *  All rights reserved.
 *
 *
 *  Redistribution and use in source and binary forms, with or without 
 *  modification, are permitted provided that the following conditions are met:
 *
 *  - Redistributions of source code must retain the above copyright notice,
 *    this list of conditions and the following disclaimer.
 *  - Redistributions in binary form must reproduce the above copyright notice,
 *    this list of conditions and the following disclaimer in the documentation
 *    and/or other materials provided with the distribution.
 *  - Neither the name of the author nor the names of its contributors may be 
 *    used to endorse or promote products derived from this software without
 *    specific prior written permission.
 *
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 *
 * This program links to software with different licenses from:
 *
 *	http://www.openssl.org which includes cryptographic software
 * 	written by Eric Young (eay@cryptsoft.com)"
 *
 *	http://www.sleepycat.com
 *
 *	http://www.trolltech.com
 * 
 *
 *
 * http://www.hohnstaedt.de/xca
 * email: christian@hohnstaedt.de
 *
 */                           

</verb></tscreen>

<sect1>Credits
<p>

In this version I have the pleasure of acknowledging
<tscreen><verb>
Kerstin Steinhauff &lt;tine (at) kerstine.de&gt;
        Arts and graphics

Ilya Kozhevnikov &lt;ilya (at) ef.unn.ru&gt;
        Compiling and testing the WIN32-port

Paul Kirner &lt;kirner (at) fhwgt.de&gt;
	Providing compile and test hardware

Bugreports and feature input:
	Frank Werner &lt;Frank (at) WeSoft.de&gt;
	Peter Bieringer &lt;pb (at) bieringer.de&gt;

</verb></tscreen>

Thank you very much.

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->

<sect>Commandline options
<p>
Usage: <em>xca dbname.db &lt;options&gt;</em>
Next to the usual X commandline options. There are the following
<itemize>
<item>-v show version information and exit
<item>-k expect all following non-option arguments to be RSA keys
<item>-r expect all following non-option arguments to be Certificate signing requests
<item>-c expect all following non-option arguments to be Certificates
<item>-p expect all following non-option arguments to be PKCS#12 files
</itemize>

<p>
when invoked with one of the -k -r -c -p options, the application 
will show the details of the item and import it into the database
if desired and exit after that.
This behaviour enables xca to be used as default application for viewing
PKI items.

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->

<sect>Common actions
<p>
Many actions are common to all crypto parts.
<sect1>Importing items
<p>
The import of an item can be done by either clicking the import button on the right
or via the context menu available by right clicking on the list background.
The import function is smart enough to probe all known formats as there are:
<itemize>
<item><em>Keys:</em>  PEM private key, PEM public key, DER private key, DER public key, PKCS8 private key.
<item><em>Requests</em> DER request, PEM request.
<item><em>Certificates</em> DER certificate, PEM certificate (PKCS#12 and in future PKCS#7 certificates
	must be imported with an extra button, because they can contain more than one certificate)
</itemize>
After selecting the filename XCA will probe for the known formats of that item
and in case of an error it prompts the <em>last</em> OpenSSL error message.
It is possible to select more than one file by selecting them with SHIFT click.
In this case all items are imported one by one.

<p>
After reading the item it searches for this item in the database and if it is unique the item
is stored in the database, otherwise it shows a message containing the internal name of the item
in the database.

<sect1>Details of an item
<p>
The details dialog can be accessed by double clicking the item, by the context menu or by
the button on the right.
The details dialog shows the internal name of the item, 
which can be changed here and will be accepted when clicking <tt>Ok</tt>.

<sect1>Renaming an item
<p>
The Key can also be renamed via the context menu by right-clicking on the item
or by the <tt>Rename</tt> button on the right border.
If the new name of the item already exists in the database a <em>_01</em> will be appended to keep
the internal name unique.

<sect1>Deleting Items
<p>
Items can be deleted by the button on the right or via the context menu.
If a certificate signed by this application is going to be removed
the application will warn you once more, because you can not revoke a
deleted certificate. So only delete a certificate signed by you
if you never exported it. Certificate signing requests can be deleted
when they got signed, because they are not needed anymore. 
The request can be recovered from the resulting certificate by 
exporting the certificate to a request. 
This is however only possible if you own the private key for the 
certificate.


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->

<sect>The Wizard <label id="wizard">
<p>
The Wizard is the central part for collecting all data regarding Certificates,
Requests and Templates. It will be invoked for generating Requests, Certificates
and Templates and for changing Templates.

<sect1>Template selection
<p>
On this page the template to be used can be selected. All following pages will be 
preset to the appropriate values of the selected template. If you don't want to 
use a template just select the <tt>Empty Template</tt>.
If the checkbox labeled: <tt>Change the default extensions of the template</tt>
is checked the Wizard will show 3 more pages containing all certificate extensions.
The lazy people leave this checkbox unchecked.

<p>
For generating Certificates there is a drop-down list of all Requests that are available. 
If you don't want to sign a request but generate a certificate from scratch
or template, uncheck the checkbox to the left of the request list.
Also only for creating certificates the signer of the new certificate
can be selected wether it shall become a <em>self-signed</em> certificate
or get signed by one of the <ref id="ca_cert" name="CA certificates"> in the 
drop-down list.
<p>
This page is not shown when creating or changing templates.

<sect1>Personal settings
<p>
On this Page all personal data like country, name and Email address
can be filled in. Only the <tt>Internal name</tt> is mandatory.
The <tt>Country code</tt> field must either be empty or exactly contain
two letters representing your country code; e.g. <em>DE</em> for Germany.
If you want to create a SSL-server certificate the <tt>Common name</tt>
must contain the <em>DNS</em> name of the server.
<p>
Keys can be generated here <em>on the fly</em> by pressing the button.
If there is no usable key and you need one, they key generation is
invoked automatically.
The newly generated key will be stored in the database, 
even if you cancel the Wizard. The drop-down list of the keys
does only contain keys that were not used by any other certificate or
request. The keylist is not available for creating or changing templates.
<p>
This page does not appear when signing a request, because the request does
contain all needed data from this page.

<sect1>X509v3 Extensions
<p>
The following 3 pages do contain all fields for adjusting the certificate extensions.
It is not in the focus of this document to explain them in detail.
The most important are the <tt>Basic Constraints</tt> and the <tt>Validity</tt> range.
<p>
For more information consult the documents in <ref id="otherdoc">.
Expecially if you don't know what this is all about consider not to create any
certificates before reading those documents.

<sect2>Basic Constraints
<p>
If the <tt>CA</tt> flag is set to true the certificate is recognized by XCA and other
instances as issuer for other certificates. Server-certificates or E-Mail certificates
must have set this flag to <tt>false</tt>
<sect2>Validity Range
<p>
The <em>not Before</em> field is set to the current date and time of the
operating system and the <em>not After</em> field is set to the current date and time
plus the specified time range.

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->

<sect>RSA Keys <label id="keys">
<p>
For asynchronous encryption and signing there are keys needed. XCA only supports RSA keys
and no DSA keys. All keys are stored encrypted in the database using the 3DES algorithm.

<p>
All keys do carry a use counter which counts the times it is used. For new
requests or certificates the list of available keys is reduced to
the keys with a use counter of 0.


<sect1>Generating Keys
<p>
The dialog asks for the internal name of the key and the keysize in bits.
While searching for random prime numbers a progress bar is shown. Although the
Progressbar carries a <tt>Cancel</tt> button it has no effect clicking on it
since the underlaying <em>OpenSSL</em> routine does not support an abort.
So think twice before generating a 4096 bit key on a 80Mhz i486 PC ....
After the key generation is done the key will be stored in the database.

<sect1>Key export
<p>
Keys can be exported by either selecting the key and pressing <em>Export</em> or by
using the context-menu. This opens a Dialogbox where you can change the following settings:
<itemize>
<item>filename
<item>Outputformat (DER, PEM, PKCS#8)
<item>Public or Private Key
<item>Encryption of the exported file (yes/no)
</itemize>

The filename is the internal name plus a <tt>pem</tt> suffix.
If the desired fileformat is not PEM it is your responsibility
to change the suffix to <tt>der</tt> or <tt>pk8</tt>.
Only PKCS&num;8 or PEM files can be encrypted, because
the DER format (although it could be encrypted)
does not support a way to supply the encryption algorithm
like e.g. <em>DES</em>.
Of course the encryption is senseless if the private part is not exported.


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->

<sect>Certificate Signing Requests <label id="csr">
<p>
Certificate signing requests are described in PKCS#10 standard.
They are used to supply a Certification Authority with the 
needed information to issue a valid certificate for you 
without knowing your private key. This
includes your personal information and your public key.

<sect1>Generating a new Request
<p>
After clicking on the <tt>New Request</tt> button the Certificate Wizard will be started to ask
all needed information for generating a new Request. See: <ref id="wizard" name="Wizard">
The request generation can also be invoked by the context menu of a certificate (Export->Request).
This menu point is only available if the private key of the certificate is available.
In this case all needed data is copied from the certificate and the Wizard is not invoked.

<sect1>Request export
<p>
Requests can be exported by either the context-menu or by selecting the request and pressing
the <tt>Export</tt> button.
The only supported format for exported requests is PEM, because there is no need for 
DER formatted requests in real life. If someone needs DER formatted requests, drop me
a mail and I will implement it.

<sect1>Request details
<p>
All information contained in the request are shown. If the Keystore does contain
the private key corresponding to the request the keys internal name is shown in the
<tt>Key</tt> field.

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->

<sect>Certificates
<p>
All Certificates from the database are displayed in a tree view reflecting the chain dependencies.
If there is a CA certificate and several client certificates signed by this CA,
the client certificates can be shown by clicking on the plus sign of the CA certificate.

<sect1>CA certificates <label id="ca_cert">
<p>
XCA recognizes your CA certificates if the CA flag in the <em>Basic Constraints</em> is set to true
and if there is a corresponding private key.
In this case the <tt>CA</tt> submenu in the context-menu is enabled.

<p>
For building the chains the CA flag is disregarded instead it consideres the issuer name and
the signature to decide which certificate is the issuer.

<sect1>Generating certificates
<p>
After clicking on the <tt>New Certificate</tt> button the Certificate Wizard will be started to ask
all needed information for generating a new Request. See: <ref id="wizard" name="Wizard">
Certificate creation can also be invoked by the context menu of the certificate list background
or by the context menu of the request.
In this case the Wizard is preset with the Request to be signedi.
<p>
If in the certificate list a <em>CA certificate</em> is selected, this
certificate is preselected as signer certificate on the second page of the Wizard.

<sect1>Certificate details
<p>
The signer is the internal name of the issuers certificate, <em>SELF SIGNED</em> if it is
self signed or <em>SIGNER UNKNOWN</em> if the issuers certificate is not available.
The validity is set to <em>valid</em> if the certificate dates are valid
or to <em>Not valid</em> if the are not, regarding the internal time and date of the OS.
<p>
If the certificate was revoked, the revocation date is shown instead.

<sect1>Certificate trustment
<p>
The certificate trustment can be changed by the context menu of the certificate.
It can be set to:
<itemize>
<item><bf>Not trusted</bf> - never trust this certificate, even if we trust the issuer. 
This is the default for imported self-signed certificates.
<item><bf>Trust depends on issuer</bf> - only trust this certificate, if we trust the
issuer. This is the default for imported and generated non-self-signed certificates.
<item><bf>Always trust</bf> - always trust this certificate, even if we do not trust
the issuers certificate or if it is absent. This is the default for generated 
self-signed certificates.
</itemize>

<sect1>Certificate export
<p>
The filename can be selected in the export dialog and the Export format:
<itemize>
<item><bf>PEM</bf> - PEM encoded
<item><bf>PEM with Certificate chain</bf> - PEM encoded certificate and all issuers up to the
root certificate in one file
<item><bf>PEM all trusted Certificates</bf> - List of all PEM encoded certificates
that are marked als <em>Always trusted</em> (usually all self-signed certificates)
in one file for e.g. apache as trusted cert store.
<item><bf>PEM all Certificates</bf> - All PEM encoded certificates in one file.
<item><bf>DER</bf> - DER encoded certificate.
<item><bf>Signed PKCS#7</bf> - PEM encoded PKCS#7 structure signed by the issuer.
<item><bf>PKCS#12</bf> - PKCS#12 structure containing the certificate and the corresponding 
<item><bf>PKCS#12</bf> - PKCS#12 structure containing the certificate, the corresponding 
private key and the chain of all issuers certificates.
</itemize>
<p>
The PKCS#12 structures will be encrypted by the password you are asked for later.

<sect1>Certificate revokation
<p>
Certificates only can be revoked, if the private key of the issuers certificate
is available. The certificate will marked as revoked and the revokation date
will be stored with the certificate.

<sect1>Certificate renewal
<p>
Certificates only can be renewed, if the private key of the issuers certificate
is available. Renewal is done by creating a new certificate as a copy of the original one
with just adjusted validity dates.

<sect1>PKCS#7
<p>
PKCS#7 structures can be created by the context menu of the signing certificate.
The PKCS#7 structure can be either signed or encrypted. 
Therefore it will prompt for a file to be either signed or encrypted.
The resulting file has the original filename with ".p7s" suffix.

<sect1>CA special functions
<p>
The context menu of CA certificates does contain the <em>CA</em> submenu.
that makes the following functions available:

<itemize>
<item><bf>Serial</bf> The serial number of the next certificate
signed by this issuer.
<item><bf>CRL days</bf> The days until the next CRL release.
<item><bf>Signing Template</bf> The default template for signing certificates.
<item><bf>Generate CRL</bf> Generate the CRL by collecting all revoked certificates
and their revokation date.
</itemize>

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
</article>