
Crypto Token Configuration
==========================

Overview
--------

A cypto token is an entity used to do cryptographic operations. OpenXPKI
organizes those tokens using groups and generations. A default system
has four groups:

* certsign - represents the Issuing CA
* datasafe - used internally to encrypt sensitive data
* scep - the operational certificate of the SCEP server
* root - the root certificate of the Issuing CA chain

OpenXPKI expects that a token has only a limited lifetime and is
substituted by a successor at a certain point in time. This relation is
expressed by the generation counter.

Initial Setup
-------------

All tokens consist of a private key and a certificate, the certificate
must be present in the OpenXPKI internal database and is referenced by
the certificate identifier. The private key lives outside the OpenXPKI
systems. When using the default config, the system expects the private
key as file where the name of the file is constructed from the complete
alias name.

Root Certificate
^^^^^^^^^^^^^^^^

For production systems it is usual to have the Issuing CA under a
Root CA and manage the Root CA on a offline system. As OpenXPKI needs
the full chain of a certificate, you need to import the root certificate
first::

    openxpkiadm certificate import --file ca-root-1.crt

Issuing Certificate
^^^^^^^^^^^^^^^^^^^

After importing the root, or if you do not have a dedicated root, you
can now import the issuing certificate::

    openxpkiadm certificate import  --file ca-signer-1.crt \
        --realm democa --token certsign

This will import the certificate and also create a so called alias to
mark this certificate as issuing token. With the default config, the key
file is expected to be at /etc/openxpki/ca/democa/ca-signer-1.pem.


Datasafe Token
^^^^^^^^^^^^^^

The datasafe token is represented by a certificate but is never
exposed to the public so it is acceptable to use a self-signed
certificate here::

    openxpkiadm certificate import  --file vault-1.crt \
        --realm democa --token datasafe

The token is used for encrypting new items only as long as the certificate
is valid. Expired tokens are still needed to decrypt existing items so
never delete or overwrite them!

Token Rollover
--------------

If the lifetime of a token is approaching its end, you can just add a
new token using the same commands as above. OpenXPKI will increase the
internal generation counter and assign it to the new alias. Just make
sure your key file has the correct name! If your token key are protected
with a password, make sure that all passwords for all generations are
still accessible as long as you need the token - issuing tokens are
usually used to sign CRLs even after their active issuing period is over
and datasafe tokens are required to access archived keys or other data.




