Install the YubiHSM 2 Tools and Software

To complete the procedures in this guide, install the YubiHSM 2 tools and software that will be needed for this.

Tip

A generic prompt, *$*, is used in command line examples in this document. Depending on your command line application, your prompt may be different.

Step 1:

Unzip the downloaded archives of the SDK containing the YubiHSM libraries and tools and move the contents to an appropriate location.

Step 2:

On your Windows system, run both installers:

• yubihsm-cngprovider-windows-amd64.msi (YubiHSM Key Storage Provider)
• yubihsm-connector-windows-amd64.msi (YubiHSM Connector for Windows)

Step 3:

Set the ADCS service dependency for the YubiHSM Connector service via an elevated/admin Windows Command Prompt. This prevents an error which occurs if the ADCS services starts before the YubiHSM connector is running.

1. List the current dependencies with sc qc “certsvc”

   > sc qc “certsvc”
   [SC] QueryServiceConfig SUCCESS
   
   SERVICE_NAME: certsvc
      TYPE               : 110  WIN32_OWN_PROCESS (interactive)
      START_TYPE         : 2   AUTO_START
      ERROR_CONTROL      : 1   NORMAL
      BINARY_PATH_NAME   : C:\Windows\system32\certsrv.exe
      LOAD_ORDER_GROUP   :
      TAG                : 0
      DISPLAY_NAME       : Active Directory Certificate Services
      DEPENDENCIES       :
      SERVICE_START_NAME : localSystem
   

2. Add the YubiHSM connector dependency to ADCS with the command: sc config "certsvc" depend="yhconsrv"

   > sc config "certsvc" depend="yhconsrv"
   [SC] ChangeServiceConfig SUCCESS
   

3. Once the command is entered, the dependency can be verified with sc qc “certsvc”

   [SC] QueryServiceConfig SUCCESS
   
   SERVICE_NAME: certsvc
      TYPE               : 110  WIN32_OWN_PROCESS (interactive)
      START_TYPE         : 2   AUTO_START
      ERROR_CONTROL      : 1   NORMAL
      BINARY_PATH_NAME   : C:\Windows\system32\certsrv.exe
      LOAD_ORDER_GROUP   :
      TAG                : 0
      DISPLAY_NAME       : Active Directory Certificate Services
      DEPENDENCIES       : yhconsrv
      SERVICE_START_NAME : localSystem
   

4. To remove dependencies for ACDS, use the same command for adding depedencies with a blank depend field: sc config "certsvc" depend=""

About the YubiHSM Software

The following YubiHSM pieces of software are used in this guide. They are included as part of the archive file you downloaded from the Yubico Knowledge Base.

Default YubiHSM 2 Default Device Configuration

The YubiHSM 2 device comes with a single factory-installed authentication key whose default password is password. As part of the configuration in this guide, this default authentication key will be destroyed. If the YubiHSM 2 is reset to its default configuration, any non factory-installed objects stored on it are also destroyed. Reset instructions can be found in Factory Reset.

To ensure that the YubiHSM 2 has not been tampered with, verify that it still has the default configuration by following the steps below:

Step 1:

Do one of the following:

• If the application that calls the YubiHSM Connector is running on a local host, start the Connector with the command yubihsm-connector without additional parameters. In Windows Server 2012 SP2 or higher, yubihsm-connector.exe is located in C:\Program Files\YubiHSM Connector\.
• If the application is running on a VM or a different server, start the YubiHSM Connector on the host operating system in networking mode. For example, if the host machine’s IP address is 192.168.100.252, launch the Connector on the host OS with the command yubihsm-connector -l 192.168.100.252:12345.

Tip

For testing or debugging the YubiHSM Connector, the flag -d can be set.

Step 2:

To gain shell access to the YubiHSM 2, launch the YubiHSM Shell program by opening a Command Prompt and running the command yubihsm-shell. If a networked Connector is used, set the parameter --connect <connector URL>, for example:

$ yubihsm-shell --connector http://192.168.100.252:12345

Tip

For testing or debugging the YubiHSM Shell, the flag -d can be set.

Step 3:

To connect to the YubiHSM 2, at the yubihsm command line, type connect. A message saying that you have a successful connection is displayed.

Step 4:

To open a session with the YubiHSM 2, type session open 1 (where 1 is the ID of the default authentication key pre-installed on the device).

Step 5:

Type in the default password: password. A message confirming that the session has been set up successfully is displayed.

Step 6:

You now have an administrative connection to the YubiHSM 2 and you can list the objects available by typing list objects 0 and pressing Enter. Your results should be similar to the following:

id: 0x0001, type: authentication-key, sequence: 0

Step 7:

To exit, type quit.