The YubiHSM Setup program is used to perform the initial configuration of the primary YubiHSM 2 device so that the necessary key material is generated on it:
One wrap key to be split as described in "Key Splitting and Key Custodians" in Prerequisites and Preparations.
One application authentication key for authenticating to the YubiHSM 2 through the KSP. This allows the KSP to perform operations in the YubiHSM 2.
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 domain concept that is used to compartmentalize the YubiHSM 2 determines this behavior.
For test purposes you can set the
One audit key 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.
The YubiHSM Setup tool has a help argument that you can call to learn more about its usage.
The configuration steps to be performed upon inserting the primary factory preset YubiHSM 2 device into the air-gapped system are set out briefly below. These steps are described in detail in the subsequent "Procedure: Configuring the Primary YubiHSM 2."
Set up communication between the YubiHSM 2 tools and the device.
Run the YubiHSM Setup with the argument
ksp, specifying the Connector URL if necessary.
Start the YubiHSM Setup process and authenticate to the YubiHSM 2 device.
Add 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, does 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.
Enter the name of the domain in which you need the application authentication key and audit key to be available.
Generate the wrap key and its ID.
Split the wrap key into shares and specify the privacy threshold.
Have the wrap key custodians record their shares.
Create the application authentication key
Create the password for the application authentication key.
Create the audit key (optional).
Original default authentication key is deleted and setup process finishes.
Figure 2 – Flowchart illustrating the YubiHSM 2 setup for Windows
Step 1: Enable communication with the YubiHSM 2 device by 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:
yubihsm-connector -l 192.168.100.252:12345
In this scenario, you can verify that the Connector is running properly by typing the following URL into your web browser:
The output in the web browser should be similar to:
status=OK serial=* version=1.0.0 pid=* address=192.168.100.252 port=12345
Step 2: In the Command Prompt, navigate to a directory for which you have write access and run the YubiHSM Setup with the argument
If the application calling it is installed on a machine other than the YubiHSM Connector, use the
connector flag to specify the Connector URL, for example:
yubihsm-setup --connector http://192.168.100.252:12345 ksp
Step 3: To start the YubiHSM Setup process, type the default authentication key password
password. A message confirms that the default authentication key was used and that you are 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 is ID
0x0001 in hexadecimal format).
Step 4: You are prompted to add RSA decryption capabilities. Enter
If you are unsure what selection to make, select no (
Step 5: You are prompted for the domain(s) you need the keys to be available in. Unless you have a requirement to assign more than one domain, enter a number between 1 and 16. In this guide, we assume that domain 1 was entered. The confirmation will look like one of the following:
got domains [ One ]
Using domains: One Enter wrap keyID (0 to choose automatically):
Step 6: You are prompted to generate a wrap key and enter its ID. Do one of the following:
To manually assign a wrap key ID, type a number for the ID. As object ID
1 is already in use by the default application authentication key, we recommend assigning ID
2 to the wrap key.
To allow the system to generate a wrap key ID automatically, type
In both cases, a confirmation message like the following is displayed:
Stored wrap key with ID 0x0002 on the device
Step 7: You are prompted to specify the number of shares into which the wrap key should be split in order to be distributed to an equal number of key custodians. You are also prompted to 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 assume that the wrap key is split into three shares, of which at least two shares must be present in order to regenerate the key.
For an overview of key custodian activities, see "Key Splitting and Key Custodians" in Prerequisites and Preparations.
For test purposes, such as in a lab scenario where wrap key sharing is not crucial, it is not necessary to specify that the wrap key should be split between key custodians. Instead, you can use a single key. To do this, when configuring the device using YubiHSM Setup, indicate the number of shares to be
When prompted, do the following:
Enter the number of shares. In this example, enter
Enter the privacy threshold. In this example, enter
The wrap key thereby generated is saved to the HSM 2 device.
Step 8: When the relevant prompt is displayed, each of the three wrap key custodians should take their turn in front of the screen to record their share.
Each custodian must record the whole string presented, including the prefix (in the following example,
The following is an example of a share presented on the screen:
2-1-WWmTQj5PHGJQ4H9Y2ouURm8m75QkDOeYzFzOX1VyMpAOeF3YKYZyA… Have you recorded the key share? (y/n)
A notice is displayed, warning that the shares are not stored anywhere.
To start having the custodians record the key shares, press Enter.
The first custodian records his or her share and confirms that the share was recorded by pressing
y. The screen buffer is cleared before the next share is presented.
The next custodian records the key share for the second share, confirms it, and so on.
Step 9: You are prompted to create an application authentication key. Since object IDs
2 are already in use by the default authentication key and the wrap key respectively, the example in this guide assumes that you enter ID
3 for the application authentication key. To allow the system to generate a wrap key ID automatically, type
Step 10: Create and enter a password of at least eight (8) characters for the application authentication key. Store it so that it cannot be compromised. You will need this password later to configure the YubiHSM KSP DLL, as described in Configure the YubiHSM 2 Software. A confirmation message like the following appears:
Stored application authentication key with ID 0x0003 on the device Saved wrapped application authentication key to 0x0003.yhw
The wrapped application authentication key (in this example,
0x0003.yhw) is exported to the current working directory. Although the keys are encrypted using the wrap key, we recommend that you do not store keys - even under wrap - on network-accessible or any storage media that could be compromised. However, if you will be making a backup (and you should), leave the
*.yhw-file with the wrapped authentication key where it was saved for now, deleting it AFTER you have made 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.
When prompted to create an audit key, type
When prompted, assign a key ID to the audit key. Make a note of the ID you enter (for example, key ID
When prompted, 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 will be named
Step 12: The setup tool (in default mode) finishes by letting you know that the default authentication key has been deleted.
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.