Backing up and Restoring Keys

Backup and Restore Managed via YubiHSM Key Storage Provider

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

ADCS does not set the NCRYPT_ALLOW_EXPORT_FLAG when generating a key through the setup UI or the Install ADCSCertificationAuthority PowerShell module.

When creating an ADCS root CA key via the YubiHSM 2, we add the exportable-under-wrap Capability by default, so that back up and restore functionality is available through the following manual process:

Identify Your Private Key Container Name

Step 1:	Open an elevated command prompt/shell. To view the currently installed certificates in the Local Machine “My” store, use the `certutil` command: PS1> certutil -store My
Step 2:	Find the target certificate in the list.
Step 3:	Find the `Key Container` property of the target certificate. The Provider property should be equal to `YubiHSM Key Storage Provider`.
Step 4:	Record the `Cert Hash` property to identify the certificate.

Back up the Target Certificate

Using any available means (certmgr.msc, PowerShell, certutil), export the target certificate, but without the private key in DER format. 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. As an example, the following exports the certificate in .crt format to a file named <Cert Hash>.crt.

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

Back up the Target Private Key

Using the instructions for exporting a private key under wrap via yubihsm-shell (Back up Objects Using YubiHSM Shell), export the target private key with the label property equal to the Key Container property. The Authentication Key that performs this operation must have the export-wrapped capability set.

Restore the Target Private Key

Using the instructions for importing a private key under wrap via yubihsm-shell (Back up Objects Using YubiHSM Shell), import the target private key file to your backup YubiHSM. The Authentication Key that performs this operation must have the import-wrapped capability set.

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

Restore the Target Certificate

Step 1:	Move the target certificate file generated above to the target machine.
Step 2:	Import the certificate to the LocalMachine “My” store using your preferred method. At this point, the certificate will not have an associated private key.
Step 3:	Use the `-repairstore` functionality of `certutil` to re-associate the certificate to the private key. Make sure that the target private key is visible via the YubiHSM KSP, using PS1> certutil -key -csp "YubiHSM Key Storage Provider" This command lists all private keys (and their corresponding container names — which are equal to the Label property in the YubiHSM visible to the current Authentication Key).
Step 4:	Open an elevated prompt and execute the command: PS1> certutil -repairstore MY <Cert Hash>
Step 5:	Repeat the steps under Identify Your Private Key Container Name to verify that the certificate has been associated with the YubiHSM Key Storage Provider and has the correct `Key Container` property value.

Back up and Restore Keys Using YubiHSM Shell

Back up Objects Using YubiHSM Shell

Make sure you have a Wrap Key with the Capabilities export-wrapped, import-wrapped and applicable Delegated Capabilities set:

$ yubihsm-shell -a get-pseudo-random --count=32 --out=wrap.key
...
yubihsm-shell -a put-wrap-key -c export-wrapped,import-wrapped
   --delegated=sign-pkcs,decrypt-pkcs,exportable-under-wrap --in=wrap.key
...
Stored Wrap key 0xd581

When this Wrap Key is present, any Object in the same Domain and with the Capability exportable-under-wrap and Capabilities matching the Wrap Key’s Delegated Capabilities can be exported:

$ yubihsm-shell -a generate-asymmetric-key -A rsa2048
   -c exportable-under-wrap,sign-pkcs,decrypt-pkcs
...
Generated Asymmetric key 0x6e77
yubihsm-shell -a get-wrapped --wrap-id=0x6e77 --object-id=0xd581
   -t asymmetric-key --out=key_6e77.yhw
...

You now have an encrypted backup of the Asymmetric Key 0x6e77 in the file key_6e77.yhw.

Important

The file wrap.key here contains the cleartext version of the Wrap Key loaded into your YubiHSM and should therefore be considered sensitive information that needs to be protected.

Back up Objects Using YubiHSM Setup

The tool yubihsm-setup can be used to back up all exportable objects at once:

$ 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

Restore Objects Using YubiHSM Shell

Assuming a fresh device where you want to restore the previously backed up key 0x6e77:

$ 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
yubihsm-shell -a put-wrapped --wrap-id=0xd581 --in=key_6e77.yhw
...
Object imported as 0x6e77 of type asymmetric-key