xca/doc/xca.sgml

<!doctype linuxdoc system>


<article>

<title>XCA - X Certificate and key management

<author>(c) by Christian Hohnst&auml;dt, <tt>christian@hohnstaedt.de</tt>

<date>April 2020 - Version 2.3.0

<abstract>

This application is intended for creating and managing X.509 certificates, certificate requests, RSA, DSA and EC private keys, Smart-cards and CRLs.
Everything that is needed for a CA is implemented.
All CAs can sign sub-CAs recursively. These certificate chains are shown clearly.
For an easy company-wide use there are customisable templates that can be used for certificate or request generation.
All cryptographic data is stored in a SQL database.
SQLite, MySQL (MariaDB), PostgreSQL and MicrosoftSQL (ODBC) databases are supported.

</abstract>

<toc>

<sect>Introduction

<p>
This application is intended as certificate- and key-store and as
signing application issuing certificates.

<p>
All data structures (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 data structure
into the database file, while exporting means to write the data structure
from the database file to the filesystem to be imported into an other application.

<p>
When opening a new database the first time, it needs a password to encrypt the
private keys in the database. This is the default password. Every time this
database is opened the application asks for the password. This input dialog
may be canceled and the database is still opened successfully.
However, the access to the keys is not possible without supplying the
correct database password every time a key is used.

<p>
When setting an empty password, XCA will never ask again for a password
when opening this database. This can be useful when playing around with test certificates or if all private keys are on security tokens.

<p>
The database password can be changed by the Menu item <em>Extra-&gt;Change DataBase password</em>

<p>
The different cryptographic parts are divided over 5 Tabs: Keys, Requests, Certificates, Templates and Revocation lists.
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 is identified by an internal name which
is always shown in the first column as long as the columns are not reordered by the user.

<sect1>File Formats

<p>

There are several default file formats to exchange cryptographic 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> formated 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 - 2018 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:

 - https://www.openssl.org which includes cryptographic software
   written by Eric Young (eay@cryptsoft.com)"

 - https://www.qt.io/

</verb></tscreen>

<sect1>Credits

<p>

<tscreen><verb>

Kerstin Steinhauff &lt;tine (at) kerstine.de&gt;
        Arts and graphics

</verb></tscreen>

Thank you very much.

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

<sect>Miscellaneous
<sect1>Updating from versions earlier than 2.0.0

<p>

Older versions of XCA used a simple serial
proprietary database for storing the cryptographic items.
Starting with version 2.0.0 this has changed to SQL.
For file based databases the SQLite database format is used.
Since XCA uses SQL, it can also be connected to a network database.
The databases <em>mySQL</em> and <em>PostgreSQL</em> are tested.
Please use the <em>Open Remote DataBase</em> menu item to connect to a remote host.
The main disadvantage of the old format leading to the switch to SQL
was the inaccessibility by external tools. Since years users ask for
command-line access to the database.
The new database can be queried
by external tools like <em>sqlite3</em> or <em>sqlitebrowser</em>
to extract verify or modify content.
Please see <ref id="extract" name="Extracting items">

<p>

When opening a legacy database, it will be converted to the new format after
backing up the original database.

Please be careful with older XCA versions.
XCA before 1.4.0 will overwrite the new SQLite database during database open.

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

<sect1>Download

<p>

The most recent stable version of XCA can be downloaded from
<url url="http://hohnstaedt.de/xca/index.php/download" name="XCA download">

<p>

The current (unstable) HEAD of development can be downloaded and tested via
<url url="https://github.com/chris2511/xca/" name="XCA devel on github">
Please do not hesitate to contact me for information about branches.

<sect1>DH Parameters

<p>

Diffie Hellman parameters can be created by XCA.
It does neither need nor use the parameters.
Applications like OpenVPN however need them and so XCA provides this
functionality for users convenience.

<sect1>Entropy sources for XCA

<p>

Entropy is a very important topic for key generation.
OpenSSL comes with a good pseudo random number generator.
XCA seeds it very thoroughly.
<enum>
  <item>During startup
    <itemize>
      <item>The OpenSSL seeding mechanism <tt>RAND_poll()</tt>.
            It uses <tt>/dev/urandom</tt> where possible and the
            screen content on Windows.
      <item>XCA also tries to pull at most 256bit from <tt>/dev/random</tt> and <tt>/dev/hwrng</tt> each.
      <item>A <tt>.rnd</tt> state file in the XCA application directory is
            read on startup and erased afterwards to avoid replays.
    </itemize>
  <item>Before any key or parameter generation a "re-seeding"
    is done. Some say re-seeding is not necessary, but
    all say it does not harm.
    <itemize>
      <item>XCA collects entropy by mouse and keyboard events and its timing.
            (<tt>XcaApplication.cpp: bool XcaApplication::eventFilter()</tt>)
            We are on a desktop host after all.
      <item>256bit from <tt>/dev/urandom</tt> (unix/Mac)
    </itemize>
  <item>A <tt>.rnd</tt> state file in the XCA application directory
        is written whenever XCA finishes.

  <item>When managing a token or generating a key on a token that supports
        <tt>C_GenerateRandom</tt> and <tt>C_SeedRandom</tt>, XCA will:
          <itemize>
            <item>Seed the token with own random data.
            <item>Seed the OpenSSL CSPRNG by random bytes from the token.
          </itemize>
</enum>



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

<sect>Command Line Options

<p>

Usage: <tt>xca [-d new.xdb] [-v] [-x] [-i &lt;index-file&gt;]
		[-I &lt;directory&gt;] &lt;files&gt;</tt>

Next to the usual X command line options. There are the following

<itemize>
	<item>-v show version information and exit
	<item>-d set the database filename (only needed to create a new db)
	<item>-x exit after processing all command line options
	<item>-i creates an OpenSSL index file containing all certificates
	<item>-I creates an OpenSSL index file for each CA in the given,
		existing directory containing all issued certificates.
</itemize>

There are some deprecated legacy options: [ -k ] [ -r ] [ -c ] [ -p ] [ -7 ] [ -l ] [ -t ] [ -P ]

Before XCA 0.9.0, the type of the items had to be given. This was removed since.
Just put all keys, certificates, requests and the database unsorted on the command-line.
For backwards compatibility those options are ignored when found.

<p>

Usually after importing the items from command-line
the application will startup as usual. With the -x
option given it will exit after finishing the import dialog. This is useful if XCA is used as default application for viewing certificates, keys or requests.

<p>

<sect1>Extracting items <label id="extract">

<p>

The sqlitebrowser may be used to examine the elements of the database.

The database schema is documented <url url="database_schema.html" name="here">.
All cryptographic items are stored as base64 DER format and must be
decoded before feeding them to OpenSSL: <em>| base64 -d | openssl &lt;x509|req|crl|pkcs8&gt; -inform DER ...</em>

<p>
Extract the private key with internal name 'pk8key' from the database
<code>
sqlite3 ~/xca.xdb "SELECT private FROM view_private WHERE name='pk8key'" | base64 -d | openssl pkcs8 -inform DER
</code>

<p>
Extract a CRL
<code>
sqlite3 ~/xca.xdb "SELECT crl FROM view_crls WHERE name='ca'" | base64 -d | openssl crl -inform DER
</code>

<p>
Modify the comment of an item with id 3
<code>
sqlite3 ~/xca.xdb "UPDATE items SET comment='My notes' WHERE id=3"
</code>

The item names are not required to be unique anymore. Each table view in XCA has an optional
column "Primary key" that may be shown to get the ID of the item in the database.

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

<sect>Common Actions

<p>

Many actions are common to all cryptographic parts and are mentioned here once for all.
The goal of this application is to provide an easy to use signing-tool and
also a common place for all selected PKI items like requests or certificates.

<sect1>Column Handling

<p>

Column visibility can be changed by the context menu of the table header
or the "columns" sub menu of the table context menu.
It shows all available columns with check-boxes to show or hide them.

<enum>
  <item>Column actions:
    <itemize>
      <item><em>Reset:</em> Reset column order and visibility to the default.
      <item><em>Hide Column:</em> Hide the current column.
		Only shown in the context menu of the column header
    </itemize>

  <item>Common columns:
    <itemize>
      <item><em>Internal name:</em> Name of the item in the database.
      <item><em>No.:</em> A simple counter to easily count the items.
      <item><em>Primary key:</em> Unique number to identify an item in the
	database. See <ref id="primary_key" name="Database primary key">.
      <item><em>Date:</em> Date of the appearance in this XCA database.
		See <ref id="date_and_source" name="Date and Source">
      <item><em>Source:</em> Origin of this item.
		See <ref id="date_and_source" name="Date and Source">.
      <item><em>Comment:</em> A multi-line free text input, see <ref id="comment" name="Comment">.
    </itemize>

  <item>Private Key columns:
    <itemize>
      <item><em>Type:</em> One of <tt>RSA</tt>, <tt>DSA</tt>, <tt>EC</tt>
      <item><em>Size:</em> Key size in bits.
      <item><em>EC Group:</em> Curve name of the EC key.
      <item><em>Use:</em> Number of certificates and requests using this key.
      <item><em>Password:</em> Protection of the key.
		See: <ref id="keys" name="RSA, DSA and EC Keys">.
    </itemize>

  <item>Certificate and request columns:
    <itemize>
      <item><em>Subject:</em> The complete subject name.
      <item><em>Subject hash:</em> Subject hash used by OpenSSL
		to lookup certificates. See
		<url url="https://www.openssl.org/docs/man1.0.2/apps/c_rehash.html"
			name=" (c_rehash, openssl x509 -hash)">.
      <item><em>Subject entries:</em> Displays single entries of the subject.
		The list represents the content of the
		<ref id="objectids" name="dn.txt"> file.
      <item><em>X509v3 Extensions:</em> Displays a textual representation
		of the selected extension.
      <item><em>X509v3 Extensions:</em> Displays a textual representation
		of the selected extension.
      <item><em>Key name:</em> Internal name of the key in the private keys tab.
      <item><em>Signature algorithm:</em> Signature algorithm used to sign the
		certificate or request.
    </itemize>

  <item>Request columns:
    <itemize>
      <item><em>Signed:</em> Whether the request is already signed or not.
      <item><em>Unstructured name:</em> CSR specific attribute.
      <item><em>Challenge password:</em> CSR specific attribute.
      <item><em>Certificate count</em> Number of certificates in the database with the same public key.
    </itemize>

  <item>Certificate columns:
    <itemize>
      <item><em>CA:</em> CA Basic Constraints flag
      <item><em>Serial:</em> Serial number
      <item><em>MD5 / SHA1 / SHA256 fingerprint:</em> Certificate fingerprint
      <item><em>Start date:</em> Not before date.
      <item><em>Expiry date:</em> Not after date.
      <item><em>Revocation:</em> Revocation date of this certificate if revoked.
      <item><em>CRL Expiration:</em> CRL expiration, if this is a CA
    </itemize>

</enum>

<p>

Columns can be resized and rearranged.
This configuration is stored in the database and will be reassigned next time
this database is opened.

<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 into the list.
The import function is smart enough to probe all known formats independent
of the file extension:

<itemize>
	<item><tt>Keys:</tt>  PEM private key, PEM public key,
		DER private key, DER public key, PKCS#8 private key, SSH public key.
	<item><tt>Requests</tt> DER request, PEM request
	<item><tt>Certificates</tt> DER certificate, PEM certificate
		(PKCS#12 and PKCS#7 certificates must be imported with an
		extra button, because they may contain more than
		one certificate and key)
</itemize>

After selecting the filename XCA will probe for the known formats of that item
and in case of an error it prompts the <tt>last</tt> OpenSSL error message.
It is possible to select more than one file by selecting them with SHIFT click.

Also the <tt>Import</tt> menu may be used to load items. Next to the file-types
above, it also supports <tt>PEM</tt> import. PEM describes the encoding
instead of the file-type. So a PEM file can be any type of private key, CRL
certificate or CSR. This import facility discovers the type and loads it.

<p>

When importing more than one Key, CRL, Certificate or Request
all items are shown in a Multi-import dialog.
When importing a PKCS#7 or PKCS#12 item, the contained keys and certificates are shown in the Multi-import dialog.
By using the Multi-import dialog the items can be examined, imported or dropped.

<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 this 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 names of the issuers certificate and the corresponding key are click-able and their
content will be shown on "double-click"

<sect1>Renaming an Item

<p>

An Item can be renamed via the context menu by right-clicking on the item,
by pressing &lt;F2&gt; or by the <em>Rename</em> button on the right border.

<sect1>Deleting Items

<p>

Items can be deleted by the button on the right or via the context menu.
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
transforming the certificate to a request.
This is however only possible if you own the private key of the
certificate. Multiple items may be selected to delete them all at once.

<sect1>Searching Items

<p>

The displayed list of items can be reduced by the search-input at the
bottom right. It affects all tabs. It does not only search inside the displayed columns but the whole content of the items. It searches the internal name,
issuer, subject, extensions, PKCS#10 attributes and token provider.

<sect1>Date and source of appearance <label id="date_and_source">

<p>

XCA tracks the time and source of any newly appeared item.
Both can be seen when selecting <em>Properties</em> in the
context menu of an item, or by enabling the <em>Source</em> or
<em>Date</em> columns.

The source may be one of the following
<itemize>
<item>Imported
<item>Generated
<item>Transformed
<item>Token
<item>Legacy Database
</itemize>

The content of the date and source fields will never be part of an exported item.

<sect1>Comments <label id="comment">

<p>
XCA allows to insert multi-line comments for all items. They can be edited
by the properties dialog. When showing the <em>Comment</em>
column, it will display the first line of the comment field.

XCA itself uses the comment field of certificates and requests
to leave a note during important operations:

<itemize>
<item>Applied templates during certificate or request generation
<item>Generated keys during certificate or request generation
<item>Signing date, time and internal name of the issuing CA when a request gets signed.
</itemize>

The content of the comment field will never be part of an exported item.

<sect1>Database primary key <label id="primary_key">


<p>
When inserting an item into the database a new, unique id
will be generated and used as primary key in the database.
If the item shall be found in the database by external tools,
the <tt>items.id</tt> can be used to uniquely identify the item.
The internal name cannot be used, since it is not necessarily unique anymore.

This ID will never be used outside the database.

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

<sect>The Certificate Input Dialog<label id="wizard">

<p>

This input dialog is the central part for collecting all data regarding certificates,
requests and templates. It will be invoked whenever such an item is going
to be created or, in case of a template, is altered.

<sect1>Source

<p>

This page is not shown when creating or changing templates.

<sect2>Signing Request

<p>

If it is desired to either enroll a certificate from a PKCS#10 request
by a local CA, or to create a certificate from a request by self-signing it,
the request can be selected here. In the later case the private key of
the request must be available.

<sect2>Signing

<p>

Either self-signing or the CA certificate for signing may be selected here.
Additionally, the desired signing algorithm can be adjusted.
The drop-down list contains all <ref id="ca_cert" name="CA certificates">
with an available private key.

<sect2>Signature Algorithm

<p>

Usually SHA256 or higher should be used, but
since older windows versions including XP can not handle them,
you may opt to use SHA1. The default signing algorithm may be
selected by the <em>Options</em> menu.

<sect2>Templates

<p>

The fields of the certificate can be preset by the values of a template
by selecting it and clicking <em>Apply all</em>.
Templates can be mixed by applying the subject of one template and then
applying the extensions of an other by using the
buttons <em>Apply subject</em> and <em>Apply extensions</em>

<sect1>Personal Settings

<p>

<sect2>Subject

<p>

On this Page all personal data like country, name and email address
can be filled in.
The <tt>Country code</tt> field must either be empty or exactly contain
two letters representing your country code; e.g. <tt>DE</tt> for Germany.
If you want to create an SSL-server certificate the <tt>Common name</tt>
must contain the <tt>DNS</tt> name of the server. Alternatively the subject-alternative-name
extension may be used to define additional DNS names, even wildcards. In this case
the CommonName must be repeated here, because TLS clients disregard the CommonName
in case the subject-alternative-name extension exists.
If the <tt>internal name</tt> is empty, the common name will be used
as internal name.
It will also be used as default internal name, if a new key is created here.

<p>

Other rarely used <tt>name-entries</tt> can be selected in the dialog below.
By using this table instead of the explicit entries above,
the order of the entries can be adjusted.
A new line can be added via the <em>Add</em> button.
The current line can be deleted via the <em>Delete</em> button.
Existing lines can be exchanged and reordered by moving the row-header (containing the row-number) around.
All items can be added more than once, even those from above. This is not very usual but allowed.

<p>

The list of the 7 explicit distinguished name entries may be adjusted in the options dialog
at <ref id="expDN" name="Explicit subject entries">

<p>

<sect2>Private Key

<p>

Keys can be generated here "on the fly" by pressing the button.
The name of the new key will be preset by the common name of the certificate.
The newly generated key will be stored in the database and stay there,
even if the input dialog is canceled. The drop-down list of the keys
only contains keys that were not used by any other certificate or
request. The key-list is not available for creating or changing templates.
By checking <tt>Used keys too</tt> the list contains all available
keys. Use this with care. You're likely doing something wrong when using this
option.

<p>

This tab does not appear when signing a request, because the request
contains all needed data from this tab.
Select "Modify subject of the request", if you want to modify it anyway.
The content of the subject Tab will then be preset with the content of the
request.

<sect1>X509v3 Extensions

<p>

The next three tabs contain all fields for adjusting the certificate extensions.
It is not in the focus of this document to explain them all 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">.
If you don't know what this is all about please read those documents before
creating any certificates.

<sect2>Basic Constraints

<p>

If the type is set to <tt>Certification Authority</tt>,
the certificate is recognized by XCA and other
instances as issuer for other certificates.
Server-certificates or E-Mail certificates should set this extension to
<tt>End entity</tt> (strongly recommended)
or disable it completely by setting it to <tt>Not defined</tt>

<sect2>Validity Range

<p>

The <tt>Not before</tt> field is set to the current date and time of the
operating system and the <tt>Not after</tt> field is set to the current
date and time plus the specified time range.
When applying time ranges, the expiry date (not after) is calculated by taking
the currently configured start date (not before) and adding the time range.


<p>

For templates the specified times are not saved, because it does not make much sense.
Rather the time range is stored and automatically applied when selecting this
template. Applying the time range means to set notBefore to "now" and notAfter
to "now + time range". If the <tt>midnight</tt> button is set both dates will be
rounded down and up to midnight.

<sect2>Advanced

<p>

Any extension, not covered on the other tabs can be added here as
defined in OpenSSL nconf. The validity can be checked by clicking
<tt>Validate</tt>. All extensions from all tabs will be shown here
to see them all in their final form. Click on <tt>Edit</tt> to continue
editing the extensions here.

Refer to the OpenSSL X509v3 configuration for more details: <url url="http://www.openssl.org/docs/apps/x509v3_config.html">

<sect3>Certificate Policies

<p>

The following example of <tt>openssl.txt</tt> also works in the advanced tab
to define certificate policies

<tscreen><verb>

certificatePolicies=ia5org,1.2.3.4,1.5.6.7.8,@polsect

[polsect]

policyIdentifier = 1.3.5.8
CPS.1="http://my.host.name/"
CPS.2="http://my.your.name/"
userNotice.1=@notice

[notice]

explicitText="Explicit Text Here"
organization="Organisation Name"
noticeNumbers=1,2,3,4

</verb></tscreen>

Adding more than one AuthorityInfoAccess entry is also possible here:

<tscreen><verb>
authorityInfoAccess=@aia_sect

[aia_sect]
OCSP;URI.1=http://www.some.responder.org/
OCSP;URI.2=http://www.some.other-responder.org/
caIssuers;URI.3=http://server.whatever.org/cert-path
caIssuers;URI.4=ldap://server.whatever.org/xxx,yyy
</verb></tscreen>

<p>

When exporting existing Certificates to templates, the extensions will
be translated to OpenSSL config file format.

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

<sect>Smart-cards (Security Tokens)

<p>

Since XCA 0.8.0 the use of Smart-cards (Security tokens) is supported.
It is based on the PKCS#11 standard. The Options dialog contains a list
to add one or more PKCS#11 providers (libraries).
This is not restricted to Smart-cards but includes all type of security tokens like USB tokens.

Up to version 1.0.0 only RSA keys on security tokens were supported.
Since version 1.1.0 XCA also supports EC and DSA private keys on security tokens.
<p>

Once again: This software comes with no warranty at all! If XCA transforms your security token into a fridge, don't blame me.
For me everything worked fine and I tested it thoroughly.

<p>

On Linux the package <tt>opensc</tt> should be installed.
Please read the opensc documentation for more details.
Generally: if the opensc command-line-tool "pkcs11-tool -L" shows reasonable output, XCA will work.
Otherwise fix the opensc setup.
I had a functional setup with a "Reiner SCT" and a DELL keyboard with integrated card reader and TCOS Netkey E4 cards.
I also used Aladdin Etoken very successfully (Thanks for support!). The Aladdin PKCS#11 library supports all needed features very well.

The ECC token support was tested with the www.cardcontact.de ECC tokens.
The OpenDNSSEC SoftHSMv2 was used as PKCS#11 reference implementation
to test all the token algorithms and certificate and key download functionality
to the token.
<p>

Before the keys of a token can be used, they must be imported into XCA.
This means that XCA reads the token and shows the keys and certificates on the token.
They can then be imported partially or completely
via the Multi-import dialog to be used by XCA.
It is not unusual that a token contains more than one key or certificate.
It is of course possible to create your own keys on the token.
When selecting a token-key for signing, XCA verifies that the
corresponding token is available.

If the Card reader supports a secure PIN input by a built-in keyboard,
it will be used by XCA and it will not ask for the PIN but waits for the Pin-pad
input.

The following actions with smart-cards are supported:

<itemize>
	<item>Import keys and certificates from the token.
		(Token->Manage Security token)
	<item>Everything you can do with other keys can be done with tokens,
		too.
	<item>On export, only the Public key is exported.
	<item>Change the PIN and SO PIN of a token.
	<item>Create a key on the token. (Button New Key)
	<item>Store an existing key or certificate on the token.
		(Context menu of the item)
	<item>Delete certificates and keys from the token.
		(Context menu of the item)
	<item>Initialize cards and the user PIN via SO PIN
</itemize>

Existing, non-deletable, built-in certificates of Smart-cards may be ignored.
A new CA certificate can be created and self-signed by the Smart-card key.
It can then be used to issue end-entity certificates, containing other RSA, DSA or EC keys, sign imported certificate requests or generate CRLs

<sect1>Key Management on the Token

<p>

XCA assumes for every private key on the card a corresponding public key.
When managing cards, XCA only searches for public keys.
There is thus no need to enter a PIN. When using the the key for signing
the corresponding private key on the card is selected and a PIN must be entered.

<p>

Accordingly, every time a key is generated on the card,
a public/private key-pair is generated.
Every time a key is stored on the card, XCA creates a public
and a private key object.

<p>

Firefox always only looks for private keys on the card.
If XCA does not show a key, which is however recognized by Firefox
a missing public-key object is the cause.

<sect1>The Token Menu

<p>

The menu item: <tt>Token</tt> is accessible if a PKCS#11 library was loaded and initialized.

<sect2>Managing Smart-cards

<p>

Security token specific operations are collected below
the menu-item <tt>Token</tt>

<sect3>Manage Security Token

<p>

This is the Multi import dialog, which allows to view and select the items to be imported.
When started it reads the content of the selected token.
Additionally, it shows token information in the bottom-right corner and allows to delete and rename
items directly on the token.

<sect3>Initializing Tokens

<p>

Initializing tokens is done via the menu item <tt>Initialize token</tt>. During this process either a new SO PIN must be supplied or the old SO PIN must be given. Additionally XCA asks for the label of this token.

<p>

After this operation succeeded, the User PIN is uninitialized and must be initialized via <tt>Init PIN</tt>

<sect3>Deleting Items from the Token

<p>

Just delete the item as usual. XCA will then ask whether the item shall also be removed from the token.
Items on the token that were not yet imported can be deleted via the "Manage security token" menu.

<sect3>Changing PINs

<p>

The User PIN and SO PIN can be changed via the <tt>Token</tt> menu and also via the key context-menu. In this case the correct token containing the key will be enforced.

<sect2>Tested Providers

<p>

The following providers were used for testing:

<itemize>
	<item>OpenSC: default provider for a lot of different cards and
		readers. Deleting keys or certificates is currently not supported.
		<itemize>
		<item>The support of Netkey 4E cards is currently restricted.
			Only import and using the keys and certificates
			is possible.
		<item>Feitian PKI cards work with the following restrictions:
			<itemize>
			<item>The cards must be initialized outside XCA with
				<tt>pkcs15-init</tt>
			<item>Storing keys onto the card crashes because of
				<tt>assert(0)</tt> in card-entersafe.c in
				opensc-0.11.13
			<item>Deleting items does not work, because it is not
				implemented in opensc-0.11.13/card-entersafe.c.
			</itemize>
		</itemize>
	<item>Aladdin eToken PKIclient-5.1: Works perfectly.
		Read public keys from the token, write private keys to the
		token, generate keys on the token, write certificates to the
		token and delete them from the token.
	<item>Linux only: OpenCryptoki (IBM): may be used as a pure software
		token, but also supports TPMs and other IBM crypto processors
	<item>www.cardcontact.de OpenSC branch supports RSA and EC Keys.
		Downloading keys to the token is not supported.
	<item>OpenDNSSEC SoftHSMv2 supports all mechanisms in software.
		A great reference to test the PKCS#11 library interface.
</itemize>

<sect2>Tested compatibility with other applications

<p>

For interoperability tests I used the Aladdin eToken together with the
Aladdin PKIclient 5.1 software and OpenSC with the Feitian PKI-card.
<itemize>
<item>Aladdin: /usr/lib/libeTPkcs11.so
<item>Feitian: /usr/lib/opensc-pkcs11.so (default)
</itemize>
I initialized the token as follows:

<itemize>
	<item>Generate CA certificate with software key
	<item>Generate server certificate with software key
	<item>Generate client certificate with a key generated on the token
	<item>Generate 2nd client certificate with software key
	<item>Copy the software-key of the 2nd client certificate onto the token
	<item>Copy the 2 client certificates onto the token
	<item>Export CA certificate as PEM (ca.crt)
	<item>Export server cert as PKCS12 without password (server.p12)
	<item>Export server cert as "PEM Cert + key" without password
			 (server.pem) for Apache2
</itemize>

<sect2>Firefox / Mozilla -> Apache

<p>

<itemize>
	<item>Enable PKCS#11 token in Firefox:
		Edit-&gt;Preferences-&gt;Advanced:
		(Security Devices): (Load) Load PKCS#11 Device:
		/usr/lib/libeTPkcs11.so
	<item>Import CA certificate: Edit-&gt;Preferences-&gt;Advanced:
		(View Certificates) (Authorities): (Import)
	<item>Prepare apache config with:

<tscreen><verb>
SSLEngine on
SSLCertificateFile      /etc/apache2/ssl/server.pem
SSLCertificateKeyFile   /etc/apache2/ssl/server.pem
SSLCertificateChainFile /etc/apache2/ssl/ca.crt
SSLCACertificateFile    /etc/apache2/ssl/ca.crt
SSLVerifyClient         require
SSLVerifyDepth          10
</verb></tscreen>

	<item>Connect with Firefox to the server. Firefox will prompt you
		to select one of the 2 client certificates. Both work.
</itemize>

<sect2>OpenVPN

<p>

The relevant server config is as follows:

<tscreen><verb>
pkcs12 server.p12
</verb></tscreen>

<p>

The client config is:

<tscreen><verb>
ca ca.crt
pkcs11-providers /usr/lib/libeTPkcs11.so
pkcs11-id 'Aladdin\x20Knowledge\x20Systems\x20Ltd\x2E/eToken/002882d2/F\xC3\xBCr\x20den\x20Firefox/D1A7BFF94B86C061'
</verb></tscreen>

The pkcs11-id can be obtained with the command:
<tt>openvpn --show-pkcs11-ids /usr/lib/libeTPkcs11.so</tt>


<sect>RSA, DSA and EC Keys <label id="keys">

<p>

For creating certificates, keys are needed.
All keys are stored encrypted in the database using the 3DES algorithm.
The password can be changed for each key. The password type means:
<itemize>
<item>common: The database password provided during database load
<item>private: The key has its own password, which is not stored by XCA. This can be set and reset via the context menu of the key
<item>PIN: Security tokens are usually protected by a PIN
<item>No password: Public keys don't need a password
</itemize>
<p>

All keys carry a use counter which counts the times it is used.
When creating new
requests or certificates the list of available keys is reduced to
the keys with a use counter of 0. This can be overridden by the check-box
next to the key list.

<p>
When importing an EC key with explicit curve parameters,
the corresponding curve OID is searched and set if found.

<p>
When exporting the key via SQL from the database,
see <ref id="extract" name="Extracting items"> openssl asks for the password,
which is either the database password or its own password in case the
password type is <tt>private</tt>.

<sect1>Generating Keys

<p>

The dialog asks for the internal name of the key and the key-size in bits.
For EC keys, a list of curves is shown. It contains all X9.62 curves and many others.

<p>

EC Brainpool curves are also supported when linking with OpenSSL 1.0.2.

<p>
Even if the drop-down list only shows the most usual key sizes, any other value
may be set here by editing this box.
While searching for random prime numbers a progress bar is shown in the
bottom of the base application.
After the key generation is done the key will be stored in the database.

<p>

When checking the <tt>Remember as default</tt> box, the settings
(Key-type, key-size or EC curve) will be remembered and preset for the
next key generation dialog. This option is not available
when generating token keys.

<p>

For every connected token providing the Key-generate facility an entry in the
drop-down menu of the key-types will be shown.
It contains the name of the token and the valid key-sizes.

<p>

In case of EC keys generated on a token, the list of possible curves
is restricted based on informations provided by the token (Key size and FP/F2M).
The token may support even less ECParameters / OIDs. When selecting an EC curve
not supported by the token an error will occur.
Please consult the documentation of the provider of the PKCS#11 library.

<sect1>Key Export

<p>

Keys can be exported by either selecting the key and pressing <em>Export</em>
or by using the context-menu.
It may be chosen to export the key to the clipboard as PEM public, SSH2 public
or unencrypted PEM private format.
In case of a file export a dialog-box opens where next to the filename one of the
following formats may be selected:

<itemize>
	<item><bf>PEM public</bf> the public part of the key in PEM format
	<item><bf>DER public</bf> the public part of the key in DER format
	<item><bf>SSH2 public</bf> the public part of the key in SSH2 format
	<item><bf>PEM private</bf> the private key unencrypt in PEM format
	<item><bf>PKCS#8 encrypted</bf> the encrypted private key in PKCS#8 format
	<item><bf>DER private</bf> the private key in binary DER format
	<item><bf>PEM encrypted</bf> the private key in PEM format with an OpenSSL specific
		extensions for encryption
	<item><bf>PKCS#8 unencrypted</bf> the private key unencrypted in PKCS#8 format
</itemize>

The filename is the internal name plus a <tt>pem</tt>, <tt>der</tt>, <tt>pk8</tt> or <tt>pub</tt> suffix.
When changing the file-format, the suffix of the filename changes accordingly.
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. <tt>DES</tt>.
Of course, encryption does not make sense if the private part is not exported.

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

<sect>Certificate Signing Requests <label id="csr">

<p>

Certificate signing requests are described in PKCS&num;10 standard.
They are used to supply a Certification Authority with the
needed information to issue a valid certificate
without knowing the private key. This
includes personal information, the public key and additional extensions.

<p>

It is not necessary to generate a request prior to signing it by your CA
or before self-signing it. Simply start generating the certificate directly.
People using the OpenSSL command line tools are used to generate a request
with "openssl req -new ..." and then signing it .
This is not necessary with XCA.

<p>

Tracking signed CSR with XCA can be done by the <em>Signed</em> and
<em>Certificate count</em> columns of the certificate signing request
tab. The <em>Signed</em> column is an information stored in the database
whenever a CSR was used used issue a certificate. Also an automatic comment
is left in the comment of the CSR.
It does not depend on the certificate remaining in XCA.
The <em>Certificate count</em> column displays the number of certificates
with the same public key.

<p>
<sect1>Generating a new Request

<p>

After clicking on the <tt>New Request</tt> button the Certificate dialog will be started to ask
all needed information for generating a new Request. See: <ref id="wizard" name="The Certificate input dialog">

<p>

The request generation can also be invoked by the context menu of a certificate (Transform->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 Certificate dialog is not invoked.

<sect1>Request Export

<p>

Requests can be exported by the context-menu or by the button on the right.

<itemize>
<item><bf>Clipboard</bf> Writes all selected requests in PEM format to the Clipboard.
<item><bf>File</bf> Write the request into a file in PEM or DER format.
<item><bf>OpenSSL config</bf> Create and store an OpenSSL configuration file which can be used to generate a similar request with openssl (openssl req -new -config &lt;file&gt;)
</itemize>

<sect1>Request Transformation

<p>

A request transformation creates a new database entry based on the selected request

<itemize>
<item><bf>Template</bf> Create a XCA template with the values of the request.
<item><bf>Public Key</bf> Extract the public key from the request and store it in the Private Keys Tab.
<item><bf>Similar Request</bf> Starts the Certificate input dialog preset with all values from the current request to create a new request.
</itemize>

<sect1>Request Details

<p>

All information contained in the request are shown. If the key-store contains
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 will recognize CA certificates if the CA flag in the <tt>Basic Constraints</tt>
is set to true.
If there is a corresponding private key, the <tt>CA</tt>
sub-menu in the context-menu will be enabled.

<p>

For building the chains the CA flag is disregarded, because there are some
CAs without this flag.
Instead it considers the issuer name and the signature to decide which certificate is the issuer.
In case of more than one possible issuer, the one with the latest
expiry date will be used as issuer to collect all issued certificates.
 
<sect1>Generating certificates

<p>

After clicking on the <tt>New Certificate</tt> button the Certificate input dialog will be started to ask
all needed information for generating a new Certificate. See: <ref id="wizard" name="The Certificate input dialog">
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 Certificate input dialog is preset with the request to be signed.

<p>

If a <tt>CA certificate</tt> is selected in the certificate list, this
certificate will be preselected as issuing certificate.

<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 issuer's certificate is not available.
The validity is set to <em>valid</em> if the certificate's dates are valid
or to <em>Not valid</em> if they are not, compared to the
internal time and date of the OS.

<p>

If the certificate is revoked, the revocation date will be shown instead.

<p>

On the <em>Subject</em> and <em>Issuer</em> tab the distinguished name is
also displayed in a format defined in RFC2253 for copy&amp;paste.

<sect1>Certificate Export

<p>
<itemize>
<item><bf>Clipboard</bf> Copy all selected certificates to the clipboard as PEM file
<item><bf>File</bf> Export to external file.
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 as <em>Always trusted</em>
		(usually all self-signed certificates) in one file for e.g.
		apache as trusted certificate store.
	<item><bf>PEM all Certificates</bf> - All PEM encoded certificates
		in one file.
	<item><bf>DER</bf> - DER encoded certificate.
	<item><bf>PKCS#7</bf> - DER encoded PKCS#7 structure containing
		the certificate.
	<item><bf>PKCS#7 with Certificate chain</bf> - DER encoded
		PKCS#7 structure containing the
		certificate and all issuers up to the root certificate.
	<item><bf>PKCS#7 all trusted Certificates</bf> - DER encoded
		PKCS#7 structure containing all
		certificates that are marked as <em>Always trusted</em>
	<item><bf>PKCS#7 all Certificates</bf> - DER encoded PKCS#7 structure
		containing all certificates.
	<item><bf>PKCS#12</bf> - PKCS#12 structure containing the certificate
		and the corresponding private key
	<item><bf>PKCS#12</bf> - PKCS#12 structure containing the certificate,
		the corresponding private key and the chain of all
		issuers certificates.
	<item><bf>PEM cert + key</bf> - concatenation of the private key
		and certificate in a format used by apache or the
		X509 patch for OpenSSH.
	<item><bf>PEM cert + PKCS8 key</bf> - concatenation of the
		private key in PKCS&num;8 format and certificate.
</itemize>

<item><bf>Token</bf> Store certificate on the Security token containing the private key
<item><bf>Other token</bf> Store certificate on any Security token
<item><bf>OpenSSL config</bf> Create an OpenSSL config file from the content of this certificate, which can be used to generate a similar certificate with openssl (openssl req -new -x509 -config &lt;file&gt;)
</itemize>

<p>

When exporting PKCS#12 structures you are asked later for an encryption
password.

<sect1>Certificate Transformation

<p>

A certificate transformation creates a new database entry based on the selected certificate.

<itemize>
<item><bf>Public Key</bf> Extract the public key from the certificate and store it in the Private Keys Tab.
<item><bf>Request</bf> Create a PKCS#10 request by using the data from the certificate. The private key of the certificate must be available for this option.
<item><bf>Similar Certificate</bf> Starts the Certificate input dialog preset with all values from the current certificate to create a new certificate.
<item><bf>Template</bf> Create a XCA template with the values of the request.
</itemize>

<sect1>Certificate revocation

<p>

Certificates can only be revoked, if the private key of the issuer's certificate
is available. The certificate will be marked as revoked and the revocation date
and reason will be stored with the CA certificate.

If more than one unrevoked certificate of the same issuer is selected, all of them will be revoked
at once with the same revocation date and reason. The context menu shows this by adding
the number of selected certificates in squared brackets.

<p>

To generate a CRL, revoke the appropriate certificates and select CA->Generate CRL in the context-menu of the signing certificate.

<sect1>Certificate renewal

<p>

Certificates can only be renewed, if the private key of the issuer's certificate
is available. Renewal is done by creating a new certificate as a copy of the original one
with adjusted validity dates.

Use the <tt>Revoke old certificate</tt> check-box to automatically revoke the old
certificate.

If more than one certificate of the same issuer is selected, all of them will be renewed
at once with the same validity dates. The context menu shows this by adding
the number of selected certificates in squared brackets.

<sect1>CA special functions

<p>

The context menu of CA certificates contains the <em>CA</em> sub-menu,
which makes the following functions available:

<itemize>
	<item><bf>Properties</bf>
	<item><bf>Generate CRL</bf> Generate the CRL by collecting all
		revoked certificates and their revocation date.
	<item><bf>Manage revocations</bf> Displays all revocations and allows to manipulate them.
</itemize>

<sect2>CA Properties
<p>
<itemize>
	<item><bf>CRL days</bf> The days until the next CRL release.
	<item><bf>Signing Template</bf> The default template for
		issuing certificates.
</itemize>

<sect2>Manage revocations
<p>
Non existing certificates may be revoked by adding the serial number of the certificate.
Since version 1.3.0 it is not required anymore to keep revoked certificates in the database,
because the revocation information is stored together with the CA certificate.


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<sect>Templates

<p>

Templates are special to XCA and not interchangeable with other applications.
They store all informations to create certificates or requests.

<p>

To use templates, just create a new certificate or request and apply one
of the templates (or parts of it) in the <tt>Source</tt> Tab.
Usually you have the distinguished name parts, that never change and properties (extensions) that define the use of the certificate.
You may apply the whole template or only the subject or only the extensions.

<p>

Next to the 3 default templates for CA, TLS server and client
certificates, customized templates may be created. Templates are not signed,
they are just a collection of common values for different certificates.
Therefore XCA does not care if any duplicates exist in the list of templates.

<p>

An easy way to create templates is to export an existing certificate or
PKCS#10 request to a template. Just select <tt>Transform->Template</tt>
in the context-menu of the item. The private key of the
Certificate or Request is not needed.

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

<sect>Certificate Revocation Lists

<p>

All certificates are issued for a restricted period of time.
However it may happen that a certificate should not be used or becomes invalid
before the "not after" time in the certificate is reached. In this case
the issuing CA should revoke this certificate by putting it on the list of
revoked certificates, signing and publishing it.

<sect1>Generation of Certificate revocation lists

<p>

In XCA this can be done by the context-menu of the CA and the
"revoke" entry in the context-menu of the issued certificate.
First all invalid certificates must be marked as revoked and
then a Certificate Revocation List should be created and will be stored in the
database.

<p>

<sect>Options

<p>

The options dialog can be found in the file menu. All options are saved
in the database and do not depend on the operating systems registry or
configuration files.

<p>

<sect1>String settings

<p>

This option applies to all strings converted to ASN1 strings.
The selected string type is automatically set to
the smallest possible and allowed type, covering all contained characters.

<p>

The list of allowed string types can be selected:

<itemize>
	<item><bf>PKIX in RFC2459 (default)</bf>All string types are
		set as described in RFC2459
	<item><bf>No BMP strings</bf> All strings containing non printable
	  characters are regarded as errors.
	<item><bf>PKIX UTF8 only</bf> All string types are selected according to
	  RFC2459 for entities issued after 2004, which means that almost all
	  distinguished name entry types are set to UTF8.
	<item><bf>All strings</bf>All string types are allowed.
</itemize>

<p>

<sect1>Default hash algorithm

<p>

Older Windows versions and OpenSSL versions can not handle
SHA256 and SHA512. This option allows to set the hash algorithm to SHA1
for instance.

<p>

<sect1>Suppress success messages

<p>

After importing and generating new items a success message is shown.
This switch disables the messages.

<p>

<sect1>Don't colorize expired certificates

<p>

Since version 0.9.2 the expiration dates of certificates will be colorized.
Red means expired or not yet valid. Yellow indicates certificates that only
have 4/5 of their lifetime until expiration.
The CRL expiration date will be marked red 2 days before expiration.

<p>

<sect1>Translate established x509 terms

<p>

It is usually more clear to read "commonName" instead of e.g (german) "Allgemeine Bezeichnung". Same is true for "Extended key usage" or "Basic constraints".
With this setting the translated terms are shown and the Tool-Tip of the
entry shows the established term. If not set, the established term will be displayed
and the Tool-Tip contains the translation.

<p>

<sect1>Only use hashes supported by the token when signing with a token key

<p>

The PKCS#11 token does probably not support all possible hashes for
a signature operation. I.e. the EC and DSA signing algorithms are currently only
defined with SHA1 in the PKCS#11 specification.

XCA does the hashing part of the digital signature in software outside
the token and uses the token to sign the hash.
That's why XCA may use additional hashing algorithms like ecdsaWithSha256.

If other applications that probably use the token hashing algorithms shall use the
token, this option should be set.

<p>

<sect1>Disable legacy Netscape extensions

<p>

With this option set the input and use of the legacy Netscape extensions
will be suppressed. The certificate input dialog has no Netscape tab,
the request and certificate columns don't show the Netscape extensions
and when applying a template or converting certificates, the Netscape extensions
are removed.
However, the details of certificates and requests still show the Netscape extensions if they exist.

<p>

<sect1>Mandatory subject entries

<p>

A list of mandatory distinguished name entries may be specified to
get a warning, whenever issuing a certificate that lacks one or more listed
entries. This requirement is not checked when editing templates,
because templates may have empty entries that will be filled during
the rollout of the certificate.

<p>

<sect1>Explicit subject entries<label id="expDN">

<p>

This list may be used to change the list of the usual 7 distinguished name entries
shown in the subject tab of the Certificate / Request / Template generation dialog
to better fit ones needs.

When activating the <em>Dynamically arrange explicit subject entries</em> option,
the explicit entries are rearranged by the name to be edited.

If the name is empty, the entries are unchanged. Otherwise, the entries of
the name to be edited are displayed first, followed by the entries of the
list above not mentioned in the name to be edited.

<p>

<sect1>PKCS#11 provider

<p>

Here you can select the path to one or more PKCS#11 libraries on your system.
If the list is empty, the <tt>Token</tt> menu will be unavailable.

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<sect>Object IDs<label id="objectids">

<p>

Private Object IDs and OID lists for the distinguished name or extended key
usage can be added in files listed below.
The files are:

<itemize>
	<item><bf>oids.txt</bf> additional Object IDs
	<item><bf>eku.txt</bf> Content of <tt>ExtendedKeyUsage</tt>
	<item><bf>dn.txt</bf> Content of <tt>DistinguishedName</tt>
</itemize>

The search path for all the files is listed below.
All files except <em>oids.txt</em> are searched in the order listed below
and search stops at the first file found.
The <em>oids.txt</em> file is searched in reversed order and all
<em>oids.txt</em> files found are loaded.

<p>

<bf>Unix</bf>

<itemize>
	<item>$HOME/.xca/
	<item>/etc/xca/
	<item>PREFIX/share/xca/ <newline>PREFIX is usually /usr or /usr/local
</itemize>

<p>

<bf>Windows</bf>

<itemize>
	<item>CSIDL_APPDATA\xca, which is something like<newline>
		C:\Documents and Settings\username\Application Data\xca<newline>
		or C:\Users\username\AppData\Roaming\xca
	<item>Installation directory <newline>e.g.: C:\Programs\xca
</itemize>

<p>

<bf>MacOSX</bf>

<itemize>
	<item>$HOME/Library/Application Support/data/xca
	<item>/Applications/xca.app/Resources
</itemize>

The path of the user settings directory depends on the
operating system and version.
The path where XCA looks for this file is shown in the
<tt>About</tt> dialog of XCA as <tt>User settings path</tt>.

<p>

<sect1>New OIDs <label id="new_oids">

<p>
All Object IDs that are not official, but belong to your company
or organisation can be added in the file <tt>oids.txt</tt>.
All possible locations for this file are searched and all <tt>oids.txt</tt> files
found are loaded. This way the application-installer adds
some in /usr/share/xca, the Administrator in /etc/xca and the user in
$HOME/.xca. The format of this file is:<newline>
<bf>OID</bf>:<bf>shortname</bf>:<bf>longname</bf><newline>
Leading and trailing spaces between the colons and the text are ignored.
Lines starting with a <bf>#</bf> are ignored.

<p>

<sect1>OID lists

<p>

The files containing OID lists (<tt>eku.txt, dn.txt</tt>)
are handled in a different way, only the first one found is used.
The format of this files is one entry per line. The entry can be either the
numerical OID like <tt>1.3.6.1.5.5.8.2.2</tt>, the short name like
<tt>iKEIntermediate</tt> or the long name <tt>IP security end entity</tt>.
Lines starting with a <bf>#</bf> are ignored.
If this files shall contain new in-official OIDs, they must be also mentioned
in one of the <tt>oids.txt</tt> files.

<p>

<sect1>Adding your company specific Subject entry

<p>

If you want to / need to add your own company specific subject
entry to your certificate it can be done without recompiling XCA.

<enum>
  <item>Add its OID with short name and long name to one
        of the <tt>oids.txt</tt> file listed in <ref id="new_oids" name="New OIDs"> like:<newline>
        <tt>1.3.6.1.4.1.12345.1: zodiacSign: Zodiac Sign</tt>
  <item>Add the OID, short name or long name to the first read <tt>dn.txt</tt>
        On Linux: <tt>cp /usr/share/xca/dn.txt ~/.xca/dn.txt && echo "zodiacSign" >> ~/.xca/dn.txt</tt>
  <item>Start XCA, open your database and goto <tt>Options->Distinguished name</tt>. In the <tt>Explicit subject entries</tt> select <tt>Zodiac Sign</tt>, click <tt>Add</tt>, move it by dragging it in the list and click OK when satisfied.
  <item>Create a new certificate and see.
</enum>

<sect>Step by Step guides

<p>

Beginners may follow these steps to easily create their first certificates.
This guide shows the minimal requirements for various tasks.  For more
advanced use of XCA, users are encouraged to familiarize themselves with
the applicable standards.

<sect1>Setting up a Root CA Certificate

<p>
<enum>
  <item>Click the <bf>Certificates</bf> tab.
  <item>Click the <bf>New Certificate</bf> button.
  <item>Make sure the <bf>Source</bf> tab is showing, clicking it if necessary.
    <itemize>
      <item>At the bottom of the panel, ensure that the
            <bf>"&#91;default&#93; CA"</bf>
	    template is showing, and click the <bf>Apply all</bf> button.
            This will fill in appropriate values under the <bf>Extensions</bf>,
	    <bf>Key Usage</bf>, and <bf>Netscape</bf> tabs.
    </itemize>
  <item>Click the <bf>Subject</bf> tab.
    <itemize>
      <item>Type in the internal name; this is for display purposes
	    in the tool, only.
      <item>Fill in the required fields in the upper Distinguished
	    Name section (Country name, State/Province, Locality,
            Organization, Common name, E-Mail address).
            The common name can be something like "ACME Certificate Authority".
      <item>If you want to add in any additional parts to the
            distinguished name, use the <bf>Add</bf> button.
      <item>Select the desired private key or generate a new one.
    </itemize>
    <item>Click the <bf>Extensions</bf> tab.
    <itemize>
      <item>The Time Range is probably fine (10 years). If you want
	    to change the duration, then change it and click <bf>Apply</bf>.
    </itemize>
    <item>The CRL distribution point will be part of the issued certificates.
          It should however be thought about a common URL for all of them like
          <tt>http://www.example.com/crl/crl.der</tt>
    <item>Click the <bf>OK</bf> button at the bottom.
</enum>

You may wish to now issue an (initially) empty CRL.  Follow the instructions
given for issuing CRLs below, except that you do not actually revoke any
certificate.

</sect1>

<sect1>Creating a CA-Signed Host Certificate

<p>

<enum>
  <item>Click the <bf>Certificates</bf> tab.
  <item>Click the <bf>New Certificate</bf> button.
  <item>Make sure the <bf>Source</bf> tab is showing, clicking it if necessary.
    <itemize>
      <item>At the bottom of the panel, select the template
            <bf>"&#91;default&#93; TLS_server"</bf> (or another suitable
            template, if you have created your own)
            and click the <bf>Apply</bf> button.
	    This will fill in appropriate values under the <bf>Extensions</bf>,
	    <bf>Key Usage</bf>, and <bf>Netscape</bf> tabs.
      <item>In the Signing section, select the certificate that
	    will be used to sign the new certificate.
    </itemize>
  <item>Click the <bf>Subject</bf> tab.
    <itemize>
	<item>Type in the internal name; this is for display purposes
	      in the tool, only.  For host certificates, the host
              FQDN (fully qualified domain name) is not a bad choice.
	<item>Fill in the required fields in the upper "Distinguished
	      Name" section (Country code, State/Province, Locality,
              Organization, Common name, E-Mail address).  For host
              certificates, the common name must be the FQDN to which you
              wish users to connect. This need not be the canonical
              name of the host, but can also be an alias.  For example,
              if <tt>pluto.example.com</tt> is your web server
              and it has a DNS CNAME entry of <tt>www.example.com</tt>,
              then you probably want the Common Name value in the certificate
              to be
              <tt>www.example.com</tt>.
	<item>If you want to add in any additional parts to the
	      distinguished name, use the drop-down box and <bf>Add</bf>
              button.
	<item>Select the desired private key or generate a new one.
    </itemize>
  <item>Click the <bf>Extensions</bf> tab.
    <itemize>
      <item>Change the Time Range if desired and click <bf>Apply</bf>.
      <item>In the event that you need to revoke any certificates in the
            future, you should designate a certificate revocation list
            location.  The location must be unique for this root certificate.
            XCA exports CRLs in either PEM or DER format with appropriate
            suffixes, so this should be considered when selecting the URL.
            Selecting a URI something like
            <tt>http://www.example.com/crl/crl.der</tt>
            is probably suitable.

            On the "CRL distribution point" line, click the <bf>Edit</bf>
            button.
            Type in the desired URI, then click <bf>Add</bf>.
            Add in any additional desired URIs in the same fashion.
            Click <bf>Validate</bf> and <bf>Apply</bf>.
            (Alternate mechanisms such as OCSP are beyond the scope of
            this guide.)
    </itemize>
  <item>Click the OK button at the bottom
</enum>

</sect1>

<sect1>Creating a Self-Signed Host Certificate

<p>
This procedure is almost identical to that of creating a CA-Signed
certificate with the following exceptions:

<enum>
  <item>When creating certificate, select "Create a self signed certificate"
        under the <bf>Source</bf> tab.
  <item>Self-signed certificates cannot be revoked, so the CRL URI should
        be blank.
</enum>

</sect1>

<sect1>Setting Up A Template

<p>

If you have, or expect to have, multiple hosts under one domain and
signed by the same root certificate, then setting up a template for
your hosts can simplify host certificate creation and improve consistency.

<p>

The values of templates can be applied on the first tab of the
certificate-generation dialog. It can be selected, whether the subject,
the extensions or both parts of the template will be applied.
This way a subject-only template may be defined and later
applied together with the TLS_client or TLS_server template.

<enum>
  <item>Click on the <bf>Templates</bf> tab.
  <item>Click on the <bf>New Template</bf> button
  <item>Select an appropriate value for the Preset Template Values, then
        click <bf>OK</bf>
  <item>Under the <bf>Subject</bf> tab, specify an internal name for the
        template.
  <item>Fill in (or modify) any values that you wish to be populated when
        using the template.  Leave the rest blank (notably the "Common Name"
        field).
  <item>When all desired fields are filled in, click the <bf>OK</bf> button
        at the bottom of the window.
</enum>

Your template is now ready for use when creating new certificates.

Alternatively, you may export an existing Certificate or Certificate signing request
to a template by the Export-context menu of the item.

</sect1>

<sect1>Revoking a Certificate issued by a CA

<p>

<enum>
  <item>Click the <bf>Certificates</bf> tab.
  <item>Right-click on the certificate that you want to revoke
        and select <bf>Revoke</bf>
  <item>Right-click the CA certificate that was used to sign the certificate
        being revoked.  Select <bf>CA</bf> --> <bf>Generate CRL</bf>
  <item>Click the <bf>OK</bf> button in the <bf>Create CRL</bf> dialog.
  <item>Click on the <bf>Revocation lists</bf> tab in the main window.
  <item>Right-click on the CRL you just generated and select <bf>Export</bf>.
        Select the desired format (probably DER) and click <bf>OK</bf>
  <item>Copy the exported CRL to the location published in the issued
        certificate's CRL Distribution Points.
  <item>Optionally, delete older CRLs for the same CA certificate.
</enum>

</sect1>

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<sect>Appendix
<p>
Here one can find several examples for file formats:
<sect1>PEM
<p>
<tscreen><verb>
-----BEGIN CERTIFICATE-----
MIIC0zCCAjygAwIBAgIQKNOqLomUfJxugwU5FHGCSjANBgkqhkiG9w0BAQQFADBf
MQswCQYDVQQGEwJVUzEXMBUGA1UEChMOVmVyaVNpZ24sIEluYy4xNzA1BgNVBAsT
LkNsYXNzIDIgUHVibGljIFByaW1hcnkgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkw
HhcNOTcxMDEzMDAwMDAwWhcNMDQwMTA1MjM1OTU5WjBDMREwDwYDVQQKEwhWZXJp
U2lnbjEuMCwGA1UECxMlVmVyaVNpZ24gQ2xhc3MgMiBPblNpdGUgSW5kaXZpZHVh
bCBDQTCBnTANBgkqhkiG9w0BAQEFAAOBiwAwgYcCgYEA3CqZnW4z/LtBdsQ5Ho33
dueQD3RVYWFyPPg3SxsfCOkwHXDFFolgM0ZIf8bQmj12mMOhwaxS0Re5FARphlxh
T7NlZYtjou4hfEGvrXJAw02Rs0m+mPtXx1ousEun7wkk84GdOMWS2kqnmFGp2DB2
LWrWry9+2xEqhftlYFpF6BsCAQOjga0wgaowDwYDVR0TBAgwBgEB/wIBADBEBgNV
HSAEPTA7MDkGC2CGSAGG+EUBBwEBMCowKAYIKwYBBQUHAgEWHGh0dHBzOi8vd3d3
LnZlcmlzaWduLmNvbS9ycGEwMQYDVR0fBCowKDAmoCSgIoYgaHR0cDovL2NybC52
ZXJpc2lnbi5jb20vcGNhMi5jcmwwCwYDVR0PBAQDAgEGMBEGCWCGSAGG+EIBAQQE
AwIBBjANBgkqhkiG9w0BAQQFAAOBgQCeTebTWFTbJFzaxCsD3432QbAsiAng0VcA
OzlDYn1BMIRT0NsrJbeTjQ8cOmvCkgesEPYsm+SniOktibXDJT+n87Can4+0CQBx
qUUsBUoG0PtMGjH4Vr/QD5sG8cMecG3FJR4CWwKitoz47h7sxM50B6RB9je1eIvS
1NMPRGO1nQ==
-----END CERTIFICATE-----
</verb></tscreen>

</article>