.. hsm2-ejbca-guide.rst

.. _hsm2-ejbca-guide-label:


===========================================
EJBCA Installation and Configuration Guide
===========================================

EJBCA and YubiHSM 2 work well together once suitable asymmetric keys have been generated on the YubiHSM 2. Even though the EJBCA Adminweb does provide functionality to generate keys on an HSM, this functionality cannot be used with YubiHSM 2. Instead, keys need to be generated using the :ref:`hsm2-setup-tool-label`. Once the keys are generated, they can be used, tested and removed using the functionality provided by EJBCA.

When generating new keys on the YubiHSM 2 for use by an existing installation of EJBCA, the relevant crypto token must be reactivated before the new keys are accessible by EJBCA.

.. Note::
  A *key alias* on EJBCA is equivalent to a *key label* on the YubiHSM 2.


Prerequisites
==============

Download the installation package suitable for the operation system from the `Yubico Developers <https://developers.yubico.com/YubiHSM2/Releases/index.html>`_ website. The following packages should be installed:

 * :ref:`hsm2-connector-label`

 * :ref:`hsm2-shell-label`

 * :ref:`hsm2-setup-tool-label`

 * :ref:`hsm2-pkcs11-guide-label`

Configuring a New EJBCA Installation
=====================================

While following the installation instructions provided by EJBCA, the instructions bellow need to be executed before deploying EJBCA for the first time:

:Step 1:	Decide how many keys to generate and what aliases they should have. See the documentation in ``EJBCA_HOME/conf/catoken.properties.sample`` for recommendation on what keys should be generated.

:Step 2:	Use the :ref:`hsm2-setup-tool-label` to generate the keys on the YubiHSM 2, one at a time.

:Step 3:	Set the environment variable ``YUBIHSM_PKCS11_CONF`` to the path of the ``yubihsm_pkcs11.conf`` file. See :ref:`hsm2-pkcs11-guide-label` for the content of that file.

:Step 4:	When configuring EJBCA, make sure to configure the following properties files:

 * ``EJBCA_HOME/conf/catoken.properties``

   .. code-block:: bash

      sharedLibrary=/path/to/yubihsm_pkcs11.so
      slotLabelType=SLOT_NUMBER
      slotLabelValue=0
      #Keys and their aliases as were created in step 2

 * ``EJBCA_HOME/conf/install.properties``

   .. code-block:: bash

      ca.tokentype=org.cesecore.keys.token.PKCS11CryptoToken
      #ca.tokenpassword=null
      ca.tokenproperties=<EJBCA_HOME>/conf/catoken.properties

 * ``EJBCA_HOME/conf/web.properties``

   .. code-block:: bash

      cryptotoken.p11.lib.255.name=<label to identify the YubiHSM 2>
      cryptotoken.p11.lib.255.file=/path/to/yubihsm_pkcs11.so


.. Note::
   The number ``255`` is just an example. It can be any “available” number. See documentation in ``EJBCA_HOME/conf/web.properties``.

Configuring an Existing EJBCA Installation
===========================================

:Step 1:	Set the environment variable ``YUBIHSM_PKCS11_CONF`` to the path of the ``yubihsm_pkcs11.conf`` file. See :ref:`hsm2-pkcs11-guide-label` for the content of that file.

:Step 2:	Configure ``EJBCA_HOME/conf/web.properties`` as follows (``255`` is just an example, read the documentation in the file for more details):

   .. code-block:: bash

      cryptotoken.p11.lib.255.name=<label to identify the YubiHSM 2>
      cryptotoken.p11.lib.255.file=/path/to/yubihsm_pkcs11.so

:Step 3:	Re-deploy EJBCA and restart the application server.

:Step 4:	On EJBCA Adminweb, create a new CryptoToken:

     a.	Go to **CA Functions > Crypto Tokens**.

     b.	Click on **Create new….**

     c.	Configure the new CryptoToken as follows:

        * **Name**: <name for this crypto token>

        * **Type**: PKCS#11

        * **Authentication Code**: <password to open a session on the YubiHSM 2. See :ref:`hsm2-pkcs11-guide-label`  > **Logging In**.

        * **PKCS#11 Library**: <from the drop down menu, choose the label you set in step 2.>

        * **PKCS#11 Reference Type**: Slot ID

        * **PKCS#11 Reference**: 0

        * **PKCS#11 Attribute File**: Default

     d. Click **Save**. If there already are keys on the YubiHSM 2, a list of them is displayed now (only keys created with the YubiHSM 2 Setup tool are displayed).

:Step 5:	On the command line, use the YubiHSM 2 Setup tool to generate keys on the YubiHSM 2, one at a time.

:Step 6:	On EJBCA Adminweb, deactivate and then re-activate the Crypto Token created in step 4. The new keys on the YubiHSM 2 are now ready to be used.


.. Important::
   The slot number of the shared PKCS#11 library must be 0.