.. hsm2-config-primary-device.rst .. _hsm2-config-primary-device-label: ========================================== Configuring the Primary YubiHSM 2 Device ========================================== The YubiHSM Setup program, which is part of the YubiHSM 2 toolset, is used to perform the initial configuration of the primary YubiHSM 2 device. This program configures the device with the requirements needed for deploying YubiHSM 2 to safely store the ADCS root CA key. Specifically, during the setup process the YubiHSM is configured so that the necessary key material is generated on the device: * One wrap key -- The wrap key is split among a determined number of key custodians, and each share is recorded by each custodian. See :ref:`hsm2-key-split-custodians-guide-label`. * One application authentication key -- The authentication key for authenticating to the YubiHSM 2 through the KSP. This allows the KSP to perform operations in the YubiHSM 2. .. Note:: This initial configuration replaces the default authentication key with a new one, which will only be operable in the same domain as the asymmetric key. The :ref:`hsm2-concepts-domain-label` that is used to compartmentalize the YubiHSM 2 determines this behavior. .. Tip:: For test purposes you can set the ``yubihsm-setup -d`` flag to keep the default authentication-key with the administrative privileges; this will allow you to delete keys on the YubiHSM 2 for test purposes only. For production purposes, however, the ``yubihsm-setup`` command must be executed without the ``-d`` flag to ensure that the factory preset authentication key is properly deleted from the YubiHSM 2 device. * One audit key -- The audit key is uised for accessing the internal audit log of the device and resetting the audit log. The audit log retains information about the last 62 operations. It is also used to purge the log if needed. Depending on your local requirements, you may not need to create an audit key. If you are unsure of your requirements, we suggest you create an audit key. The authentication key and the audit key are exported under wrap to a file in the current working directory on the machine where the YubiHSM Setup program is installed. .. Tip:: The YubiHSM Setup tool has a help argument that you can call to learn more about its usage. .. Note:: To safeguard the integrity of the device, configuration must be performed in an air-gapped environment. Summary of Configuration Steps =============================== After you have inserted the primary device into the air-gapped system, the configuration steps are diagrammed in the following image, and listed below. They are described in detail in the next section, :ref:`hsm2-config-procedure-label`. .. figure:: /graphics/pre-post-conditions-factory.png :scale: 100% :align: center **Figure: Pre- and Post-Conditions** Configuration Steps ==================== :Step 1: Set up communication between the YubiHSM 2 tools and the device. :Step 2: Start the configuration process. Run the YubiHSM Setup with the argument ``ksp``, specifying the Connector URL if necessary. :Step 3: Start the YubiHSM Setup process and authenticate to the YubiHSM device. :Step 4: Specify RSA decryption capabilities if required. If you plan to use your YubiHSM 2 exclusively with an application that only needs signing capabilities, RSA decryption is not required. Active Directory Certificate Services (ADCS), for example, do not require RSA decryption. However, if you are planning on using the same YubiHSM 2 device for something that does require the capability to decrypt RSA, then you do need RSA decryption. The Microsoft SQL Server Always Encrypted, for example, needs RSA decryption capabilities. :Step 5: Enter the names of the domains in which you need the application authentication key and audit key to be available. :Step 6: Create the **wrap key** and its ID. :Step 7: Split the wrap key into shares and specify the privacy threshold. :Step 8: Have the wrap key custodians record the number of shares required to rejoin the wrap key. :Step 9: Create the **application authentication key** that will be used to authenticate to the device by the KSP in Windows so the KSP can perform operations in YubiHSM 2. :Step 10: Create the password for the application authentication key. :Step 9: Create the **audit key** (optional). This is used to access the internal audit log of the device which holds information about the last 62 operations performed and so you can reset the audit log. The original default authentication key is deleted and setup process finishes. .. figure:: /graphics/pre-post-conditions-windows.png :scale: 100% :align: center **Figure - Flowchart illustrating the YubiHSM 2 setup for Windows** .. _hsm2-config-procedure-label: Configure Primary YubiSHM 2 Procedure ======================================= :Step 1: Enable communication with the YubiHSM 2 device by ensuring that the YubiHSM Connector service (``yhconsrv`` in Windows) is running the YubiHSM Connector on the system where the device is inserted. If the YubiHSM Connector is running on a host machine to which the YubiHSM 2 is physically connected, the Connector should be started in networked mode. For example, if the host IP address is 192.168.100.252, the Connector should be started on the host machine with the following command: .. code-block:: bash yubihsm-connector -l 192.168.100.252:12345 You can validate that the connector is running properly by typing the following URI into your browser: http://192.168.100.252:12345/connector/status. The output in the web browser should be similar to: .. code-block:: bash status=OK serial=* version=1.0.0 pid=* address=192.168.100.252 port=12345 :Step 2: Run YubiHSM Setup with the argument ``ksp``. To do this: a. Launch your command line application. b. Navigate to the directory for which you have write access and that contains the YubiHSM Setup program. c. Run the YubiHSM Setup with the argument ``ksp``. .. code-block:: bash yubihsm-setup ksp If the application calling the Setup is installed on a machine other than the YubiHSM Connector, use the connector flag to specify the Connector URL, for example: .. code-block:: bash yubihsm-setup --connector http://192.168.100.252:12345 ksp .. Tip:: The setup tool also has a help argument that you can call to learn more about its usage. :Step 3: To start the YubiHSM Setup process, type the default authentication key password: ``password`` and press **Enter**. A message confirms that the default authentication key was used and that you have successfully authenticated to the device: ``Using authentication key 0x0001.`` Object IDs are displayed in the YubiHSM Setup Tool using hexadecimal numbers, in this case the default authentication key has ID ``1``, or ``0x0001`` in hexadecimal. :Step 4: You are prompted to add RSA decryption capabilities. Do one of the following: * If you plan to use your YubiHSM 2 with ADCS exclusively, you will not need the RSA decryption capabilities, you will only need signing capabilities. Type ``n``. * If you plan on using the same YubiHSM 2 device for purposes that do require decrypting RSA, type ``y``. .. Tip:: If you are unsure what selection to make, type ``n``. :Step 5: At the prompt, enter the domain(s) you need the application authentication key and audit key to be available in. The authentication and audit keys are generated after you create the wrap key. You will only need one domain for the purposes of completing this guide. Do the following: Unless you have a requirement to assign more than one domain, type a single number between ``1`` to ``16`` and press **Enter**. In this guide, we assume that domain ``1`` was entered. Confirmation will look like the following: .. code-block:: bash got domains [ One ] or .. code-block:: bash Using domains: One Enter wrap keyID (0 to choose automatically): :Step 6: In this step you generate a wrap key and enter its ID. The wrap key is very important as it allows you to export and import objects from and to the device. For example, you would export and import objects for backup purposes, as described in the section Backup Key Material. Do one of the following: * To manually assign a wrap key ID, type the number and press **Enter**. As object ID ``1`` is already in use by the default application authentication key, we recommend you assign id ``2`` to the wrap key. Type ``2`` and press **Enter**. * To allow the system to assign a wrap key ID automatically, type ``0`` and press **Enter**. In both cases, a confirmation message similar to the following is displayed: .. code-block:: bash Stored wrap key with ID 0x0002 on the device :Step 7: Specify the number of shares to split the wrap key to distribute it equally among a number of key custodians. Also, specify the privacy threshold, which is the number of shares that must be present for the wrap key to be regenerated. For this example, we will assume that the wrap key is split into three shares, out of which at least two shares must be present in order to use the key. If there are not two key custodians present, the wrap key cannot be rejoined. At the prompt, do the following: a. Enter the number of shares. In this example, enter ``3``. b. Enter the privacy threshold. In this example, enter ``2``. When defined, the three wrap key custodians will each take their turn in front of the screen to record their respective share. A warning notice appears advising you that the shares are not stored anywhere. :Step 8: Have each custodian record their key shares. Each custodian completes these steps. a. At the prompt, record their key share. b. Confirm their key share by typing ```y`` and press **Enter**. c. Turn it over to the next custodian. The screen buffer is cleared before each share is presented. The following is an example of a share presented on the screen: .. code-block:: bash 2-1-WWmTQj5PHGJQ4H9Y2ouURm8m75QkDOeYzFzOX1VyMpAOeF3YKYZyAVd M0WY4GErclVuAC Have you recorded the key share? (y/n) A notice is displayed, warning if the shares are not stored anywhere. .. Note:: Be sure to record the shares and store them safely if you want to re-use the wrap key for this device in the future. .. Important:: Each custodian must record the whole string presented, including the prefix (in this case) ``2-1-`` which indicates the number of shares determined to be required to rejoin (or the privacy threshold) and the number of the share itself out of the total number of shares being created. .. Tip:: For non-production and test purposes, such as in a lab scenario, it is not necessary to specify that the wrap key should be shared between key custodians but instead just use one solitary key. To do this, when configuring the device using YubiHSM Setup, indicate the number of shares to be ``1`` and the privacy threshold to also be ``1``. When this step is completed, the wrap key generated is saved to the HSM 2 device. :Step 9: Create an application authentication key. This key is used to authenticate to the device by the Key Storage Provider (KSP) in Windows, allowing the KSP to perform operations in YubiHSM 2. Since object ID ``1`` and ``2`` are already in use by the default authentication key and the wrap key respectively, the example in this guide assumes that the application authentication key to be created next gets ID ``3``. Do one of the following: * To manually assign an application authentication key ID, type ``3`` and press **Enter**. * To instead allow the system to assign a wrap key ID automatically, type ``0`` and press **Enter**. :Step 10: Create and enter a password of at least eight (8) characters for the application authentication key. Be sure to store the password of the application authentication key that you will use in a way so that it cannot be compromised. You will need this password later to configure the YubiHSM KSP DLL for use later. See :ref:`hsm2-configure-software-windows-label`. Enter the application authentication key password and press **Enter**. A confirmation message appears. .. code-block:: bash Stored application authentication key with ID 0x0003 on the device Saved wrapped application authentication key to {path} 0x0003.yhw The wrapped application authentication key (``0x0003.yhw``) has been saved to the same path as the location of the YubiHSM Setup program. Although encrypted using the wrap key, we recommend that you do not store keys - even under wrap - on a network-accessible or otherwise potentially comprisable storage media. Leave the ``\*.yhw-`` file with the wrapped authentication key where it was saved for now. It will be used later to create a backup. Delete the application authentication key **after** you make the backup. :Step 11: Decide whether to create an **audit authentication key**. To log into the YubiHSM 2 with the audit authentication key, both the key ID and the password will be needed. The audit key is used to access the internal audit log of the device which holds information about the last 62 operations performed. It is also used to reset the log if needed. Depending on your local requirements, you may not need to create an audit key. If you are unsure of your requirements, we suggest you create an audit key. a. At the prompt to create an audit key, type ``y``. b. Assign a key ID to the audit key. Make a note of the ID you enter (for example, key ID ``4``). c. Enter the audit key password. Store this password so that it cannot be compromised. The audit key is exported under wrap to the current working directory. Using our example of key ID ``4``, the file is named ``0x0004.yhw``. :Step 10: The setup tool finishes by letting you know that the default, factory-installed authentication key has been deleted. .. code-block:: bash Previous authentication key 0x0001 deleted All done The YubiHSM Setup application exits. The YubiHSM 2 device is now equipped with the symmetric keys for wrap, audit, and application authentication. Verifying the Setup ==================== You can verify the results of the YubiHSM Setup program by using the YubiHSM Shell program, and logging in using the application authentication key (we used object ID ``3`` in this guide). To verify the YubiHSM Setup: :Step 1: In your command line application (where ``$`` is the prompt), run YubiHSM Shell program. To do this, if you haven’t already, launch your command line application and navigate to the directory containing the YubiHSM Shell program. Then type the following command and press **Enter**. .. code-block:: bash $ yubihsm-shell :Step 2: To connect to the YubiHSM, at the yubihsm prompt, type ``connect`` and press **Enter**. A message verifying that you have a successful connection is displayed. :Step 3: To open a session with the YubiHSM 2, type ``session open 3`` and press **Enter**. :Step 4: Type in the password for the application authentication key. You will receive a confirmation message that the session has been set up successfully. :Step 5: You now have an administrative connection to the YubiHSM 2 and can list the objects available. To list the objects, type ``list objects 0`` and press **Enter**. Your results should be similar to the following: .. code-block:: bash Found 3 object(s) id: 0x0002, type: wrapkey, sequence: 0 id: 0x0003, type: authkey, sequence: 0 id: 0x0004, type: authkey, sequence: 0 As you can see by looking at their IDs, these objects correspond to the wrap key, the application authentication key and the audit key that were just created. To obtain more information about any one of the objects, for example, the application authentication key (object ID ``3``), including its capabilities, type the following command and press **Enter**: .. code-block:: bash yubihsm> get objectinfo 0 3 authentication-key The response you receive should look similar to the following: .. code-block:: bash id: 0x0003, type: authkey, algorithm: yubico-aes-auth, label: "Application auth key", length: 40, domains: 1, sequence: 0, origin: imported, capabilities: asymmetric_gen:asymmetric_sign_pkcs:asymmetric_sign_pss: export_wrapped: import_wrapped:export_under_wrap, delegated_capabilities: asymmetric_gen:asymmetric_sign_pkcs:asymmetric_sign_pss: export_under_wrap This indicates that YubiHSM 2 as it has now been configured will later on allow the KSP to leverage the device to: * Generate asymmetric objects * Compute signatures using RSA-PKCS1v1.5 * Compute signatures using RSA-PSS * Export other objects under wrap * Import wrapped objects * Mark an object as exportable under wrap In addition, this object (the application authentication key, object ID ``3``) also has so-called delegated capabilities. Delegated capabilities define the set of capabilities that can be set or “bestowed” onto other objects that are created by it. :Step 6: To exit, type ``quit``.