.. hsm2-backup-restore.rst .. _hsm2-backup-restore-label: ================================ YubiHSM 2: Backup and Restore ================================ 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``. .. _hsm2-backup-restore-using-yubihsm-shell-label: Backup and Restore Using YubiHSM Shell ======================================= Backup ------- :Step 1: For the purpose of this guide, we will start by generating an asymmetric key that we will then make a backup of. .. code-block:: bash $ 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. :Step 2: Start by getting a pseudo random number from the YubiHSM2 and store it in a file. This will be the wrap key. .. code-block:: bash $ 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. :Step 3: Import wrap.key into the primary YubiHSM2. .. code-block:: bash ... 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. :Step 4: Make an encrypted backup of the Asymmetric Key 0x6e77 in the file key_6e77.yhw. .. code-block:: bash 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``. :Step 1: Import the wrap key into the backup YubiHSM2. .. code-block:: bash $ 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 :Step 2: Import the Asymmetric key 0x6e77 into the backup YubiHEM2. .. code-block:: bash 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 :ref:`hsm2-setup-tool-label` 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. .. code-block:: bash $ 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. .. code-block:: bash $ yubihsm-setup restore .. Note:: If the wrap key was split, the shares to reconstruct it will need to be provided in this step. .. _hsm2-backup-and-restore-using-yubihsm-ksp-windows-only-label: 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. :ref:`hsm2-backup-id-private-key-container-name-label` 2. :ref:`hsm2-backup-target-certificate-label` 3. :ref:`hsm2-backup-target-private-key-label` 4. :ref:`hsm2-restore-target-private-key-label` 5. :ref:`hsm2-restore-target-certificate-label` .. _hsm2-backup-id-private-key-container-name-label: Identify Your Private Key Container Name ----------------------------------------- :Step 1: To view the currently installed certificates in the Local Machine “My” store, open an elevated command prompt/shell by using the ``certutil`` command. .. code-block:: bash PS1> certutil -store My :Step 2: 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``. :Step 3: To identify the certificate, record the ``Cert Hash`` property. .. _hsm2-backup-target-certificate-label: 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 ``.crt``, use the command. .. code-block:: bash PS1> certutil -split -store My . .. _hsm2-backup-target-private-key-label: Backup the Target Private Key ------------------------------- Export the target private key with the ``label`` property equal to the ``Key Container`` property. :Step 1: Use an Authentication Key with the ``export-wrapped`` capability set. :Step 2: Use the instructions for exporting a private key under wrap via ``yubihsm-shell`` (see :ref:`hsm2-backup-restore-using-yubihsm-shell-label`). .. _hsm2-restore-target-private-key-label: Restore the Target Private Key -------------------------------- Import the target private key file to your backup YubiHSM. :Step 1: Use an Authentication Key with the ``import-wrapped`` capability set. :Step 2: Use the instructions for importing a private key under wrap via ``yubihsm-shell`` (see :ref:`hsm2-backup-restore-using-yubihsm-shell-label`). The imported key object should have the same ``Label`` property as the original object. .. _hsm2-restore-target-certificate-label: Restore the Target Certificate --------------------------------- Before the certificate is imported to the local machine, it does not have an associated private key. :Step 1: Move the target certificate file generated as per :ref:`hsm2-backup-restore-using-yubihsm-shell-label` to the target machine by importing the certificate to the LocalMachine “My” store. Use your preferred method. :Step 2: Re-associate the certificate to the private key by using the ``-repairstore`` functionality of ``certutil``. :Step 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). .. code-block:: bash PS1> certutil -key -csp "YubiHSM Key Storage Provider" :Step 4: Open an elevated prompt and execute the command: .. code-block:: bash PS1> certutil -repairstore MY :Step 5: 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 :ref:`hsm2-backup-id-private-key-container-name-label`.