Backup and Restore with YubiHSM Backup Keys

This document describes methods for creating a secondary YubiHSM key that is a backup of your primary YubiHSM. Topics in this document:

Backup for Large or Complex Installations

The YubiHSM 2 supports encrypted export and import of objects using a symmetric AES-CCM based scheme.

The examples below assume the default authentication key (0x0001). If you use some other authentication key make sure that it has the capability put-wrap-key and has the correct delegated capabilities, otherwise you will get a wrong permissions for operation error.

You can perform these operations using:

  • YubiHSM Shell for backing up and restoring
  • YubiHSM Setup for backing up and restoring
  • YubiHSM Key Storage Provider for backing up and restoring certificate as well as private key.

In all three cases, the process is done by taking the following steps:

  1. Create a wrap key, call it wrapkey.
  2. Import wrapkey into the primary YubiHSM2.
  3. Export other objects in the primary YubiHSM2 using wrapkey.
  4. Import wrapkey into the backup YubiHSM2.
  5. Import the objects exported in step 3 into the backup YubiHSM2.

In order for a full backup to be successful, the following conditions need to be fulfilled (any object that does not fulfill these conditions is not exported):

  • wrapkey is accessible in all the domains the other objects are available in.
  • wrapkey has delegated capabilities that include all the capabilities any other object has.
  • wrapkey has the capabilities export-wrapped and import-wrapped.
  • All other objects have the capability exportable-under-wrap.

Backup and Restore Using YubiHSM Shell

Backup

  1. For the purpose of this guide, we will start by generating an asymmetric key that we will then make a backup of.

    $ yubihsm-shell -a generate-asymmetric-key -A rsa2048 --capabilities exportable-under-wrap, sign-pkcs,decrypt-pkcs
...
Generated Asymmetric key 0x6e77
...

    OBS: This will generate an asymmetric key accessible in all domains.

  2. Start by getting a pseudo random number from the YubiHSM2 and store it in a file. This will be the wrap key.

    $ yubihsm-shell -a get-pseudo-random --count=32 --out=wrap.key

    Important

    The file wrap.key here contains the Wrap Key loaded into your YubiHSM in clear text. It should therefore be considered sensitive.

  3. Import wrap.key into the primary YubiHSM2.

    ...
yubihsm-shell -a put-wrap-key --capabilities export-wrapped,import-wrapped --delegated=sign-pkcs, decrypt-pkcs,exportable-under-wrap --in=wrap.key
...
Stored Wrap key 0xd581

    OBS: This will import a wrap key accessible in all domains.

  4. Make an encrypted backup of the Asymmetric Key 0x6e77 in the file key_6e77.yhw.

    yubihsm-shell -a get-wrapped --wrap-id=0xd581 --object-id=0x6e77 -t asymmetric-key --out=key_6e77.yhw

Restore

This assumes a fresh device where you want to restore the previously backed up key 0x6e77.

  1. Import the wrap key into the backup YubiHSM2.

    $ yubihsm-shell -a put-wrap-key -A aes256-ccm-wrap -c export-wrapped, import-wrapped --delegated=sign-pkcs,decrypt-pkcs,exportable-under-wrap --in=wrap.key -i 0xd581
...
Stored Wrap key 0xd581

  2. Import the Asymmetric key 0x6e77 into the backup YubiHEM2.

    yubihsm-shell -a put-wrapped --wrap-id=0xd581 --in=key_6e77.yhw
...
Object imported as 0x6e77 of type asymmetric-key

Backup and Restore Using YubiHSM Setup

The YubiHSM 2 Setup Tool can be used to backup and restore all exportable objects simultaneously.

Backup

OBS: This assumes that a wrap key fulfilling all the conditions mentioned above already exists in the primary YubiHSM2. For the following command line examples, we will assume that such a key has ObjectID 0xd581.

$ yubihsm-setup dump
Enter the wrapping key ID to use for exporting objects: 0xd581
...
Successfully exported object Asymmetric with ID 0x6e77 to ./0x6e77.yhw
All done

Note

When creating a wrap key using yubihsm-setup with the subcommand ksp or ejbca, an option is presented to split the wrap key into shares to be held by different custodians. It would also be possible to set the minimum number of custodians required to reconstruct the wrap key.

Important

Split and reconstruction of the wrap key is done in the software (yubihsm-setup). The YubiHSM2 itself is not aware of such split or any shares.

Restore

Running the store command will import all \*.yhw files in the current directory. If some of those files are not encrypted/wrapped with a wrap key that exists in the backup YubiHSM2, they will not be imported.

$ yubihsm-setup restore

Note

If the wrap key was split, the shares to reconstruct it will need to be provided in this step.

Backup and Restore Using YubiHSM KSP (Windows Only)

YubiHSM Key Storage Provider (KSP) enables backing up and restoring the keys managed using this tool.

Note

Microsoft Active Directory Certificate Services (ADCS) does not set the NCRYPT_ALLOW_EXPORT_FLAG when generating a key, either through the setup UI or the Install-ADCSCertificationAuthority PowerShell module.

When creating an ADCS root CA key using the YubiHSM 2, we add the exportable-under-wrap Capability by default. Backup and restore functionality is therefore available using the following manual processes.

  1. Identify Your Private Key Container Name
  2. Backup the Target Certificate
  3. Backup the Target Private Key
  4. Restore the Target Private Key
  5. Restore the Target Certificate

Identify Your Private Key Container Name

  1. To view the currently installed certificates in the Local Machine “My” store, open an elevated command prompt/shell by using the certutil command.
PS1> certutil -store My
  1. Find the target certificate in the list and then find its Key Container property. The Provider property should be the same as YubiHSM Key Storage Provider.
  2. To identify the certificate, record the Cert Hash property.

Backup the Target Certificate

Using any available means (certmgr.msc, PowerShell, certutil), export the target certificate, but without the private key in DER format.

Note

The YubiHSM does not provide a mechanism for returning the raw private key to Windows, so generating a PKCS#12 container is not currently possible.

For example, to export the certificate in .crt ``format to a file named ``<Cert Hash>.crt, use the command.

PS1> certutil -split -store My <Cert Hash>.

Backup the Target Private Key

Export the target private key with the label property equal to the Key Container property.

  1. Use an Authentication Key with the export-wrapped capability set.
  2. Use the instructions for exporting a private key under wrap via yubihsm-shell (see Backup and Restore Using YubiHSM Shell).

Restore the Target Private Key

Import the target private key file to your backup YubiHSM.

  1. Use an Authentication Key with the import-wrapped capability set.
  2. Use the instructions for importing a private key under wrap via yubihsm-shell (see Backup and Restore Using YubiHSM Shell).

The imported key object should have the same Label property as the original object.

Restore the Target Certificate

Before the certificate is imported to the local machine, it does not have an associated private key.

  1. Move the target certificate file generated as per Backup and Restore Using YubiHSM Shell to the target machine by importing the certificate to the LocalMachine “My” store. Use your preferred method.
  2. Re-associate the certificate to the private key by using the -repairstore functionality of certutil.
  3. Verify that the target private key is visible via the YubiHSM KSP: list all private keys (and their corresponding container names - which are equal to the Label property in the YubiHSM visible to the current Authentication Key).
PS1> certutil -key -csp "YubiHSM Key Storage Provider"
  1. Open an elevated prompt and execute the command:
PS1> certutil -repairstore MY <Cert Hash>
  1. To verify that the certificate has been associated with the YubiHSM Key Storage Provider and has the correct Key Container property value, repeat the steps under Identify Your Private Key Container Name.

Backup for Small or Testing Installations

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 Backup and Restore with YubiHSM Backup Keys 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 Backup and Restore with YubiHSM Backup Keys, 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

  1. Locate the wrapped key material that was previously exported by the steps in Deploy YubiHSM 2 Key Storage Provider (KSP).
  2. Set up communication between the YubiHSM 2 tools and the secondary (backup) YubiHSM 2 device.
  3. Start the configuration process and authenticate to the secondary YubiHSM 2 device.
  4. Identify the CA root key ID.
  5. Export the CA root key.
  6. Verify the key material under wrap.
  7. Restore the key material onto a secondary (backup) YubiHSM 2 device.
  8. 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:

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

  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.

  3. To open a session with the YubiHSM 2, type session open 3 and press Enter.

  4. Type in the password for the application authentication key.

    You will receive a confirmation message that the session has been set up successfully.

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

  6. 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 seed=0 asymmetric-key {rootkeyID} rootkey.yhw

    Where seed=0 does not export a privacy key seed. See EXPORT WRAPPED Command.

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

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

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

  10. 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
  1. 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.
  1. 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
  1. 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.

  1. 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}
  1. 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.
  2. 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).

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

  2. Connect to the YubiHSM 2, at the yubihsm prompt, type connect and press Enter. A message confirms that you have a successful connection.

  3. Open a session with the YubiHSM 2, type session open 3 and press Enter.

    where - 3 is the ID for your application authentication key.

  4. Type the password for the application authentication key. A message confirms that the session has been set up successfully.

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

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

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