Back Up and Restore Key Material
We strongly recommend making a backup copy of all production objects residing on your production devices, particularly once the asymmetric key has been generated on the YubiHSM 2. If there is a hardware failure of the production device, having a backup ensures that you can resume operations quickly. The backup process will result in two identical YubiHSM 2 devices with the same number of objects, keys, labels, etc.
Making specific recommendations for governance of your critical key material is out of scope for this guide. Ensure you design these security procedures to meet the requirements of your organization - and then document the procedures. In many cases, they are subject to audits.
Back Up the YubiHSM 2
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 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
- Application authentication key (ID
- Audit key (ID
4) (if created previously)
The objects were exported under wrap. The factory-installed authentication key (ID
1) on the secondary HSM 2 device will be destroyed, just as it was on the primary HSM 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.
The backup of the primary YubiHSM 2 should thus contain a duplicate of each of the objects stored on the primary device. Availability of these objects is ensured by the same application authentication key as the one used for the primary YubiHSM 2.
To guarantee integrity, perform these operations in an air-gapped environment.
Overview of Procedure
The backup procedure consists of the following steps, which are described in detail in the next section, “Restore Keys on the Secondary YubiHSM 2 Device.”
- Locate the wrapped key material that was previously exported in “Procedure: Configuring Primary YubiHSM 2” in Configure 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.
- Restore the key material onto a secondary YubiHSM 2 device.
Figure - Flowchart illustrating backup and recovery of YubiHSM 2 keys
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 on the YubiHSM 2 device.
Restore Keys on the Secondary YubiHSM 2 Device
Verify that all the keys that were previously exported from the primary YubiHSM 2 under wrap are located in a directory to which you have read access.
If the necessary keys are not yet all available on disk, you can export the keys under wrap by running the following command:
The YubiHSM Setup tool looks for files with the
For example, the following wrapped key files may be present:
If the initial authentication key (by default available as ID 0x0001) has been deleted, the new authentication application key will be identified with the flag
$ 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 still inserted into your computer, remove it and insert the secondary device.
In the directory containing the
$ yubihsm-setup restore
To start the YubiHSM Setup process, type the default authentication key password, which is
Using authentication key 0x0001
You will now start the restore procedure, by providing the minimum number of wrap key shares required by the privacy threshold defined when setting up the primary HSM 2.
When prompted, type the number of shares required by the privacy threshold. In the example used in this guide, we specified that two shares are required to regenerate the key. These must be present in order to proceed.
When prompted for share number 1, the wrap key custodian holding the first share inputs this information. A message confirms that the share was received:
Received share 2-1WWmTQj5PHGJQ4H9Y2ouURm8m75QkDOeYzFzOX1VyMpAO…
Continue to have each wrap key custodian enter the share information for each of the wrap key shares required to regenerate the wrap key. Once a 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 HSM 2 is now on the secondary HSM 2 as well:
Stored wrap key with ID 0x0002 on the device
The ID of the wrap key on the secondary device is the same as the ID of the wrap key on the primary device.
Once the wrap key has been stored on the secondary HSM 2, the YubiHSM Setup program reads the files containing the application authentication key and, if applicable, the audit key, which 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
If there are files containing wrapped objects with the
The restore process finishes 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
You should now have a secondary HSM 2 configured with the three key objects you created on the primary device earlier. Confirm that these key objects are identical to those on the primary device that was configured earlier:
In the Command Prompt, run the YubiHSM Shell program:
To connect to the YubiHSM 2, at the
To open a session with the YubiHSM 2, type
Type in the password for the application authentication key. A message confirming that the session has been set up successfully is displayed.
To list the objects, type
Depending on the order in which the keys under wrap were imported, the keys on the secondary device may not be listed in the same sequence as they are on the primary device when the
If you have verified that the secondary device now contains all of the key material that you intended to restore, you should now remove the keys under wrap on file in the current working directory. The computer’s hard drive can be erased, too.