Deploying YubiHSM 2 with Active Directory Certificate Services

This document is intended to enable systems administrators to deploy YubiHSM 2 with YubiHSM Key Storage Provider so that the Active Directory Certificate Services Certificate Authority (ADCS CA) root key is created securely on the YubiHSM 2 and so that a hardware-based backup copy of key materials has been produced.

As a guide for deployment, it covers basic topics. Instructions should be modified as required for your specific environment. It is assumed that installation is performed on a single server destined to become a production or lab Certificate Authority root. It is also assumed that you are familiar with the concepts and processes of working with Microsoft ADCS.

Plan a public key infrastructure (PKI) that is appropriate for your organization. For guidance on setting up a PKI, see Microsoft’s TechNet article on Public Key Infrastructure Design Guidance

We recommend that you install and test the installation and setup of the YubiHSM 2 in a test or lab environment before deploying to production.

Scenario: In a Windows PKI environment, protect the CA root key in hardware.

Benefits: YubiHSM 2 guards the CA root key and protects all signing and verification services using the root key.

Note

Although the screenshots in this guide are specific to Windows Server 2016, Server 2019 is also supported.

Prerequisites and Preparations

The audience of this document is expected to be an experienced systems administrator with a good understanding of Windows Server management. In addition, it helps to be familiar with the terminology, software and tools specific to YubiHSM 2. As a primer for these, refer to the :: Glossary in this guide.

In order to follow the steps provided in this guide, be sure you meet the following prerequisites, having:

  • Access to Microsoft Windows Server 2012, R2/2016, 2019 with Active Directory in an offline, air-gapped environment, such as a secure computer network that is physically isolated from unsecured networks such as the internet. You must also have elevated system privileges.
  • YubiHSM 2 software and tools for Windows downloaded from the YubiHSM 2 Release page and available on the system to be used.
  • Two (2) factory-reset YubiHSM 2 devices, one for deployment and one for backup in hardware.
  • Key custodians identified as per local requirements and available to participate. For more information about key custodians and the associated M of N key shares, see the next chapter in this guide.

Key Splitting and Key Custodians

The preferred method for backing up the YubiHSM 2 keys calls for key splitting and restoring or regenerating, often referred to as setting up an M of n scheme (Shamir’s Secret Sharing (SSS)). This process ensures no individual can export key material from the YubiHSM 2 and provides a way to control the import of key material that has been exported under wrap from one device into other devices. For example, you would export and import objects for backup purposes, as described in Backup and Restore Using YubiHSM KSP (Windows Only).

The key that is split among a predetermined number (n) of key custodians (also known as key shareholders) is known as the wrap key. Each custodian receives their own unique share. To use the key, a minimum number of shares (m) must be present so that the key can be regenerated (sometimes called “rejoined”). This minimum number of custodians is called the privacy threshold. If this threshold is not attained, the wrap key cannot be regenerated. This minimum number, n, should be larger than one.

The exact number of key shares and the privacy threshold are determined by the requirements of your organization. If your organization has policies in place that define how this procedure should be performed, be sure you know these policies before proceeding. You should also have a predetermined practice in place specifying both:

  • How the key shares must be recorded (written on paper, photographed, locally printed, or some other means) and
  • How they must be stored between uses (for example, offsite archive, safety deposit box, sealed envelope).
_images/privacy-threshold.png

Figure: Privacy Threshold

The YubiHSM Setup Tool enables you to perform the key splitting and assigning of shares to key custodians. To carry out the setup process, you need to know who the wrap key custodians will be. During setup, all key custodians must be physically present to record their shares. Exact instructions for key splitting and assigning of shares are given in Configuring the Primary YubiHSM 2 Device.

Deploying YubiHSM2 with ADCS Overview

With a YubiHSM 2 device now configured for use with YubiHSM Key Storage Provider and Microsoft Active Directory Certificate Services, the next set of steps covers the deployment in the ADCS environment. Note that YubiHSM Key Storage Provider software must be installed on the system before proceeding.

Deploying YubiHSM consists of three steps as follows. These steps are described in detail in the following procedure.

  1. Configuring the Windows Registry for the YubiHSM Key Storage Provider for the primary YubiHSM 2 device that was configured earlier
  2. Configuring ADCS (if not already present)
  3. Configuring a new ADCS CA with a root CA key being generated on the device
_images/pre-post-conditions-adcs.png

Figure: Pre- and Post-Conditions

The host that these steps are performed on is assumed to be a member server in the Active Directory domain (domain-joined, not a Domain Controller).

These instructions include steps for a basic configuration and should be performed by an experienced system administrator.

Configuring the Windows Registry

For ADCS to use the YubiHSM 2, the following registry entries need to be changed from their default values. The HKEY_LOCAL_MACHINE\SOFTWARE\Yubico\YubiHSM subkey was created during installation. Be sure to make a backup of your Registry before you make any changes. To configure the Windows Registry:

Step 1:

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

Locate and then click the registry subkey for YubiHSM (HKEY_LOCAL_MACHINE\SOFTWARE\Yubico\YubiHSM).
Step 3:

To change the URI where the connector is listening, change the following entry: “ConnectorURL”=http://127.0.0.1:12345
Step 4:

To change 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 the correct information). For our example, because the hexadecimal value of 0x00000003 resolves to 3 in the Windows Registry, change the entry as follows: “AuthKeysetID”=3
Step 5:

To change the password for the application authentication key that is stored in the registry change the entry for: “AuthKeysetPassword”={password}. The password is stored here for the Key Storage Provider to use when authenticating to the device.
Step 6:

To save your changes, exit the Windows Registry.

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 make sure that parameters are consistent between the configuration file and the Windows Registry. On Windows, the yubihsmconnector.config.yaml file is available at C:\programdata\yubiHSM\yubihsmconnector.yaml - you will need administrator rights to modify the file.

Setting Up Your Enterprise Certificate Authority

To Configure ADCS

If you already have Certification Services installed, you can skip these steps.

Step 1:On a Windows Server host, joined to an existing Active Directory domain, log on into the server as a domain administrator.
Step 2:Click Start > Administrative Tools, then click Server Manager.
Step 3:Under Roles Summary, click Add roles and features.
Step 4:Use the Add Roles and Features Wizard to add the Active Directory Certificate Services role, and click Next.
Step 5:In the Select role services wizard page, select the option for Certification Authority, then click Next.
Step 6:Complete the wizard and reboot the host if prompted.

To Configure the ADCS CA and Create the Root Key

After you have completed the feature installation, you need to create the Enterprise CA instance.

Step 1:

If you haven’t already, do the following:

  1. On a Windows Server host, joined to an existing Active Directory domain, log into the server as a domain administrator.
  2. Click Start > Administrative Tools, then click Server Manager.
Step 2:

In Server Manager, start the Add Roles and Features Wizard and select Role-based or feature based installation. Click Next.
Step 3:

In the Credentials page, confirm that you are logged in as a domain administrator. If you are not, you will not be able to create an Enterprise CA in the subsequent steps. Click Next.
Step 4:

In the Role Services page, select the option for Certification Authority, and then click Next.
Step 5:

In the Setup Type page, select the option for Enterprise CA, and then click Next.
Step 6:

In the CA Type page, select the option for Root CA, and then click Next.
Step 7:

In the Private Key page, select the option for Create a new private key, and then click Next.
Step 8:

In the Cryptography for CA page, do the following:

  1. Click Select a cryptographic provider and select RSA#YubiHSM Key Storage Provider from the list displayed. This indicates that the root key should be generated on the device.
  2. Click Key Length and select the key size you want from the list displayed. Options for key size 2048-bit or 4096-bit. The default setting is 2048.
  3. For Select the hash algorithm for signing certificates issued by this CA, select a desired hash algorithm, such as SHA256. The default setting is SHA256.
  4. Select the option to Allow administrator interaction when the private key is accessed by the CA. This allows the private key to be exported for backup purposes (so it can be restored to another server). Click Next.
Step 9:

In the CA Name page, accept the defaults. Click Next.
Step 10:

In the Validity Period page, accept the default or set another validity period appropriate for your purposes. Click Next.
Step 11:

In the CA Database page, accept the default location for logs. Click Next.
Step 12:

In the Confirmation page, the important detail is that the YubiHSM Key Storage Provider is being used to store the CA private key. Click Configure.

The Progress page appears, briefly, as the local CA database is created, and changes are written to Active Directory.
Step 13:

Finally, confirm the presence of the Configuration succeeded message in the Results page. Click Close.