Backup and Restore Key Material

We strongly recommend you make a backup copy of all production objects residing on your primary device, particularly once the CA root key has been generated on the device. If there is an unforeseen hardware failure of the primary device, having a backup ensures that you can resume operations quickly. In addition, this provides a means to backup all objects contained on a device to reside in secure hardware offline.

The backup process will result in two identical YubiHSM 2 devices with the same number of objects, keys, labels, etc.

Note

Specific recommendations for governance of your critical key material is out of scope for this guide. Ensure that you design and document these security procedures to fit the requirements of your organization. In many cases, they are subject to audits.

Backup the YubiHSM 2 Overview

The backup of the primary YubiHSM 2 is a duplicate of all of the objects stored on the primary device, to be exported under wrap and that are available using the application authentication key used.

The procedure described in this section is appropriate for testing and for smaller installations. For larger and/or more complex installations such as:

Those whose setup did not involve the YubiHSM Setup program
When moving the YubiHSM 2 device from one server to another

Review the information at YubiHSM 2: Backup and Restore to determine whether the procedures set out there are more appropriate for your situation.

This guide gives instructions for duplicating the following on the secondary device:

Wrap key (previously created with ID 2),
Application authentication key (ID 3),
Audit key (ID 4) (if created previously)

The listed objects are exported under wrap.

The factory-installed authentication key (ID 1) on the secondary YubiHSM 2 device will be destroyed, just as it was on the primary YubiHSM 2 device.

If you use actual wrap key custodians (instead of just doing a proof of concept), you will need the custodians to provide their respective wrap key shares. In the example we used in this guide, 2 out of the 3 custodians/shares must be available.

To guarantee integrity, perform these operations in an air-gapped environment.

Backup and Restore the YubiHSM 2 Procedure Overview

The backup, see YubiHSM 2: Backup and Restore, of the primary YubiHSM 2 is a duplicate of all of the objects stored on the primary device. The objects are exported under wrap onto the secondary device. The objects are available using the same application authentication key used.

For instance, when following this guide, the wrap key (created with ID 2 previously), the application authentication key (ID 3), the audit key (ID 4) (if created previously), and the CA root key will be duplicated onto the secondary device. The factory-installed authentication key (ID 1) on the secondary device will be destroyed. You will need assistance from the wrap key custodians to provide their respective wrap key shares, if applicable.

In the example we used in this guide, 2 out of the 3 shares must be available. When you create a backup, you create a duplicate of the objects on your primary YubiHSM 2 onto a secondary device. The actual backup procedure consists of steps as follows. These steps are described in detail in the following procedure.

The backup and restore procedure consists of the steps listed below the following diagram. The steps are explained in detail in the section,:ref:hsm2-restore-keys-secondary-yubihsm2-device-label.

_images/pre-post-backup-recovery-keys.png

Figure: Flowchart illustrating backup and recovery of YubiHSM 2 keys

Locate the wrapped key material that was previously exported by the steps in Configuring the Primary YubiHSM 2 Device.
Set up communication between the YubiHSM 2 tools and the secondary (backup) YubiHSM 2 device.
Start the configuration process and authenticate to the secondary YubiHSM 2 device.
Identify the CA root key ID.
Export the CA root key.
Verify the key material under wrap.
Restore the key material onto a secondary (backup) YubiHSM 2 device.
Verify the objects on the secondary device are correct.

_images/pre-post-conditions-backup-key-materials.png

Figure: Pre and Post Conditions

Tip

For test purposes* you can set the ``yubihsm-setup -d`` flag to keep the default authentication-key with the administrative privileges. This allows 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 on the YubiHSM 2.

Restore Keys on the Secondary YubiHSM 2 Device

Since the CA root key was created on the device when setting up the CA, it currently only exists on the device. To back it up using the YubiHSM Setup program, it must first be exported from the device using the wrap key that also sits on the device alongside the application authentication key and the audit key. To export the CA root key under wrap using the wrap key on the device:

In your command line application, run YubiHSM Shell program. To do this, if you haven’t already:
1. Launch your command line application and navigate to the directory containing the YubiHSM Shell program.
2. Then run the following command and press Enter.
  $ yubihsm-shell
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.
To open a session with the YubiHSM 2, type session open 3 and press Enter.
Type in the password for the application authentication key.

You will receive a confirmation message that the session has been set up successfully.
If you already know the object ID of the root CA, you can skip this step. If you need to identify the root CA, you can list the objects available.
1. To list the objects, type list objects 0 (where 0 is the session number) and press Enter.
2. You will receive a list of the objects on the device that application authentication key with ID 3 has access to, which will include the CA root key. Identify its ID.
To export the CA root key under wrap from the primary device to the local file system, in the YubiHSM Shell program, run
yubihsm> get wrapped 0 2 asymmetric-key {rootkeyID} rootkey.yhw
Verify that all the keys, that were previously exported from the primary YubiHSM 2 under wrap, reside in the same directory as the YubiHSM Setup program and that you have read access to that directory.
If the necessary keys are not yet all available on disk, export the keys under wrap. Run the following command:
yubihsm-setup dump
The YubiHSM Setup tool looks for files with the .yhw file extension in the current working directory and attempts to read and import them into the YubiHSM 2 device. The wrap key itself will be imported when the wrap key shares are provided to the tool. For example, the following files may be present:
- 0x0003-AuthenticationKey.yhw (Application authentication key under wrap)
- 0x0004-AuthenticationKey.yhw (Audit key under wrap)
- rootkey.yhw (CA root key under wrap)
- x427a-Opaque.yhw (Certificate under wrap - not referenced by this guide in the configuration of the primary HSM 2)
- x427a-AsymmetricKey.yhw (Private asymmetric key under wrap - not referenced by this guide in the configuration of the primary HSM 2)
If the initial authentication key (by default available as ID 0x0001) has been deleted, the new authentication application key is identified with the flag yubihsm-setup --authkey. For example:
$ yubihsm-setup --authkey 0x0003 dump
To begin the process of restoring the data onto the secondary YubiHSM 2, if the primary YubiHSM 2 device is inserted into your computer, remove it and insert the secondary device.

Important

Restoring a device must be performed in an air-gapped environment in order to guarantee integrity.
In your command line application (where $ is the prompt), run YubiHSM Setup with the argument restore.
1. Change the directory containing the *.yhw files,
2. Run yubihsm-setup with the restore argument:
  $ yubihsm-setup restore
To start the YubiHSM Setup process. Type the default authentication key password: password and press Enter.

A confirmation message confirms that the default authentication key was used and that you successfully have authenticated to the YubiHSM 2 device:
```
Using authentication key 0x0001
```
When prompted, type the minimum number of wrap key shares required by the privacy threshold and press Enter.

The require number of wrap key shares were defined when you set up the primary YubiHSM 2 device. In this guide, we have specified that 2 shares are required to regenerate the key. These must be present in order to proceed.

When prompted for share number 1: Have the wrap key custodian holding the first share input this information and press Enter. A message confirms that the share is received:

Received share 2-1WWmTQj5PHGJQ4H9Y2ouURm8m75QkDOeYzFzOX1VyMpAOeF3YKYZyAVdM0WY4GErclVuAC

Continue to have each wrap key custodian enter the share information for each of the wrap key shares required to regenerate the wrap key. When the sufficient number of wrap key shares have been entered by the wrap key custodians, a final message is displayed indicating that the wrap key from the primary YubiHSM 2 is now on the secondary YubiHSM 2 as well:

Stored wrap key with ID 0x0002 on the device
Note

The ID of the wrap key on the secondary device is the same as the ID of the wrap key on the primary device.

Review the output to verify Certificate Authority (CA) root key was also generated and exported along with a private asymmetric key, both under wrap.

After the wrap key has been stored on the secondary YubiHSM 2 device, the YubiHSM Setup program reads the files containing the application authentication key, the CA root key, and, if applicable, the audit key that were saved to file under wrap during the configuration of the primary device.

The output below shows that in this case, the Certificate Authority (CA) root key was also generated and exported along with a private asymmetric key, both under wrap.
reading ./0x0004.yhw
Successfully imported object Authkey, with ID 0x0004
reading ./0x0003.yhw
Successfully imported object Authkey, with ID 0x0003
reading ./0x427a-AsymmetricKey.yhw
Successfully imported object Asymmetric, with ID 0x427a
reading ./0x427a-Opaque.yhw
Successfully imported object Opaque, with ID 0x427a
reading ./rootkey.yhw
Successfully imported object Asymmetric, with ID {rootkeyID}

Review the output to note if there are files containing wrapped objects with the .yhw file extension in this directory that were exported with a wrap key other than the one reconstituted by the shares here. The Setup tool attempts to read those too, but fails gracefully. The Setup tool only restores the files it can decrypt.
Wait for the restore process to finish and the setup tool informs you that the default, factory-installed authentication key has been deleted.
```
Previous authentication key 0x0001 deleted
All done
```
The YubiHSM Setup application exits.

Verify the Duplicated YubiHSM 2

With the steps in the previous sections completed, you now have a secondary (duplicate) of the YubiHSM 2 device configured with the three key objects you created on the primary YubiHSM 2 device earlier.

Confirm that the key objects are identical on both the secondary (configured in previous section) and the primary device (configured earlier).

At your command prompt, run the YubiHSM Shell program. To do this, if you haven’t already:
1. Launch your command line application and navigate to the directory containing the YubiHSM Shell program.
2. Then run the following command and press Enter.
  $ yubihsm-shell
Connect to the YubiHSM 2, at the yubihsm prompt, type connect and press Enter. A message confirms that you have a successful connection.
Open a session with the YubiHSM 2, type session open 3 and press Enter.

where - 3 is the ID for your application authentication key.
Type the password for the application authentication key. A message confirms that the session has been set up successfully.
List the objects, type list objects 0 and press Enter.

where - 0 is session number that was given to you in step 4. Replace 0 with your session number, if it is different.
Review the output and verify that the secondary device now contains all of the key material that you intended to restore.

Depending on the order in which the keys under wrap were imported, the order of the enumerated keys on the secondary device may be different than on the primary device when using the list command. This has no practical implication and the object IDs are identical between the devices.
After you verify that the secondary device contains all of the key material that you intended to restore, remove the keys under wrap currently on file in the current working directory for the YubiHSM Setup program. The computer’s hard drive can be erased.