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 Key Splitting and Key Custodians.

  • 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 Domain 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, Configure Primary YubiSHM 2 Procedure.

_images/pre-post-conditions-factory.png

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.

_images/pre-post-conditions-windows.png

Figure - Flowchart illustrating the YubiHSM 2 setup for Windows

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:

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:

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:

  1. Launch your command line application.

  2. Navigate to the directory for which you have write access and that contains the YubiHSM Setup program.

  3. Run the YubiHSM Setup with the argument ksp.

    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:

    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:

got domains [
One
]

or

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:

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:

  1. Enter the number of shares. In this example, enter 3.
  2. 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.

  1. At the prompt, record their key share.
  2. Confirm their key share by typing `y and press Enter.
  3. 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:

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 Configure the YubiHSM 2 Software on Windows.

Enter the application authentication key password and press Enter. A confirmation message appears.

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.

  1. At the prompt to create an audit key, type y.

  2. Assign a key ID to the audit key.

    Make a note of the ID you enter (for example, key ID 4).

  3. 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.

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.

$ 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:

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:

yubihsm> get objectinfo 0 3 authentication-key

The response you receive should look similar to the following:

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.