.. hsm2-configure-software-windows.rst

.. _hsm2-configure-software-windows-label:


============================================
Configure the YubiHSM 2 Software on Windows
============================================

Before using the YubiHSM 2 on Windows, there are two YubiHSM 2 software components to be configured:

 * 	The YubiHSM 2 KSP.

 * The YubiHSM 2 Connector service.

The configuration steps are described in the sections below.

.. Important:: Make a backup of your Windows Registry before you make any changes.


Configure the KSP Settings in the Windows Registry
===================================================

To enable Microsoft Cryptographic API Next Generation (CNG) to access the YubiHSM 2 KSP, the following registry entries must be changed from their default values. The YubiHSM 64-bit KSP subkey and the YubiHSM 32-bit KSP subkey were created during the YubiHSM SDK installation:

.. code-block:: bash

   HKEY_LOCAL_MACHINE\SOFTWARE\Yubico\YubiHSM


The edits to be made produce a result like the one illustrated below:

.. image:: /graphics/registry-settings-yubihsm2-ksp.png
    :scale: 80%
    :align: center

**Figure - Registry settings for the YubiHSM 2 KSP**


:Step 1:	Click **Start > Run**, type ``regedit`` in the Run dialog box, and click **OK**.

:Step 2:	Select the registry subkey for the **YubiHSM 64-bit KSP**.

    .. code-block:: bash

       HKEY_LOCAL_MACHINE\SOFTWARE\Yubico\YubiHSM.


:Step 3:	Change the URI to the IP address and port on which the YubiHSM 2 Connector is listening by editing the following registry entry appropriately, for example:

    .. code-block:: bash

       “ConnectorURL”=http://127.0.0.1:12345


    If the Connector is listening on IP address and port ``192.168.100.252:12345``, for example, the ConnectorURL value should be changed to:

    .. code-block:: bash

       “ConnectorURL”=http://192.168.100.252:12345


:Step 4:	Enter the ID of the application authentication key (object ID ``3`` was used as an example in this guide; if you used another object ID be sure to enter that). For our example, because the hexadecimal value of ``0x00000003`` resolves to ``3`` in the Windows Registry, change the entry to:

    .. code-block:: bash

       “AuthKeysetID”=3


:Step 5:	The application authentication key password is stored in the registry for the KSP to use when authenticating to the device. Enter the new password that you created:

    .. code-block:: bash

       “AuthKeysetPassword”={password}


:Step 6:	Select the registry subkey for the ``YubiHSM 32-bit KSP``.

    .. code-block:: bash

    HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Yubico\YubiHSM


:Steo 7: Repeat steps 3-5 above.

:Step 8:	To save your changes, exit the Windows Registry.


Configure the YubiHSM 2 Connector Service
==========================================

The YubiHSM Connector service reads the configuration file ``yubihsm-connector-config.yaml``. Depending on your local setup, for instance if you are running multiple instances of the software on the same host, you may need to edit this configuration file to ensure it is consistent with the Windows Registry, i.e., that the parameters and their values are the same in the configuration file and in the Windows Registry.

On Windows, the ``yubihsmconnector.config.yaml`` file is located at ``C:\programdata\yubiHSM\yubihsmconnector.yaml`` - you will need administrator rights to modify the file.