In the event that a wrap key custodian needs to be changed from one person to another, it is recommended to generate a new Wrap key with completely new Key Shares rather than passing along the same secret from the old custodian to the new custodian.
Generating a new Wrap Key which can be recreated using the Shamir Shares requires an authentication key with certain capabilities, which is not present if you have been following our YubiHSM 2 Windows Deployment Guide.
If this is the case, a new Authentication key with the correct capabilities needs to be generated before a new Wrap Key and its shares can be created.
This process involves a factory reset which means that it is imperative that you have a verified working backup of the keys that are stored on the YubiHSM module, and that you have access to at least the minimum number of key shares needed to restore the current Wrap Key.
For more details on backing up your YubiHSM device, refer to the section Backup and Restore Key Material in the YubiHSM 2 Windows Deployment Guide
Procedure:
1. Open up a command prompt with yubihsm-shell and start a session using your authentication-key. for example authentication-key 3.
C:\yubihsm-shell.exe
Using default connector URL: http://127.0.0.1:12345
yubihsm> connect
Session keepalive set up to run every 15 seconds
yubihsm> session open 3 password
Created session 0
2. Check the YubiHSM2 contents through the YubiHSM-Shell, using the command list objects 0
yubihsm> list objects 0
Found 4 object(s)
id: 0x0002, type: wrap-key, sequence: 0
id: 0x0003, type: authentication-key, sequence: 0
id: 0x0004, type: authentication-key, sequence: 0
id: 0x10d1, type: asymmetric-key, sequence: 0
3. Generate a new backup using the current wrap-key, using the command yubihsm-setup.exe -k 3 dump
yubihsm-setup.exe -k 3 dump
Enter authentication password: password
Using authentication key 0x0003
Enter the wrapping key ID to use for exporting objects: 2
Found 4 object(s)
Successfully exported object asymmetric-key with ID 0x10d1 to ./0x10d1-asymmetric-key.yhw
Unable to export object wrap-key with ID 0x0002: Wrong premissions for operation. Skipping over ...
Successfully exported object authentication-key with ID 0x0003 to ./0x0003-authentication-key.yhw
Successfully exported object authentication-key with ID 0x0004 to ./0x0004-authentication-key.yhw
All done
4. Perform a physical reset of the YubiHSM according to Resetting Device to Factory Settings Guide
5. Restore the keys to the YubiHSM by restoring from the backup that was generated in step 3. and remember to save the default authentication key (0x0001) by adding the -d option to the yubihsm-setup restore command:
yubihsm-setup.exe -d restore
Enter authentication password: password
Using authentication key 0x0001
Enter the number of shares: 4
Enter share number: 1
...
Received share
...
Stored wrap key with ID 0x0002 on the device
reading .\0x0003-authentication-key.yhw
Successfully imported object authentication-key, with ID 0x0003
reading .\0x0004-authentication-key.yhw
Successfully imported object authentication-key, with ID 0x0004
reading .\0x10d1-asymmetric-key.yhw Successfully
imported object asymmetric-key, with ID 0x10d1
Previous authentication key 0x0001 not deleted. Make sure you know what you are doing
6. In order to replace the wrap-key on id 0x0002, run Yubihsm-setup -d ksp once more according to Configure the Primary YubiHSM 2 Device guide
At the steps 1-5, use the same values as for the existing YubiHSM.
At step 6, select a NEW id for the wrap-key, for example 7 (0x0007). Create the new key shares and ask the custodians to note them down.
At step 7, select the SAME id for the authentication-key, for example 3 (0x0003). This will terminate the YubiHSM-Setup script, which is expected.
7. Verify the objects of the YubiHSM by running the yubihsm-shell command list objects 0
yubihsm> list objects 0
Found 6 object(s)
id: 0x0001, type: authentication-key, sequence: 2
id: 0x0002, type: wrap-key, sequence: 0
id: 0x0003, type: authentication-key, sequence: 0
id: 0x0004, type: authentication-key, sequence: 0
id: 0x0007, type: wrap-key, sequence: 0
id: 0x10d1, type: asymmetric-key, sequence: 0
8. For security reasons, the wrap-key on 0x0002 and the factory authentication-key on 0x0001 can be deleted by using YubiHSM-Shell
C:\yubihsm-shell.exe
Using default connector URL: http://127.0.0.1:12345
yubihsm> connectSession keepalive set up to run every 15 seconds
yubihsm> session open 1 password Created session 0
yubihsm> delete 0 0x0002 wrap-key
yubihsm> delete 0 0x0001 authentication-key
9. Verify the objects of the YubiHSM by running the yubihsm-shell command list objects 0
yubihsm> list objects 0 Found 4 object(s)
id: 0x0003, type: authentication-key, sequence: 0
id: 0x0004, type: authentication-key, sequence: 0
id: 0x0007, type: wrap-key, sequence: 0
id: 0x10d1, type: asymmetric-key, sequence: 0
10. Exit yubihsm-shell and run yubihsm-setup -k 3 dump to export the keys using the new wrap-key
yubihsm-setup -k 3 dump
Enter authentication password: password
Using authentication key 0x0003
Enter the wrapping key ID to use for exporting objects: 7
Found 4 object(s)
Successfully exported object authentication-key with ID 0x0003 to ./0x0003-authentication-key.yhw
Successfully exported object authentication-key with ID 0x0004 to ./0x0004-authentication-key.yhw
Successfully exported object asymmetric-key with ID 0x10d1 to ./0x10d1-asymmetric-key.yhw
Unable to export object wrap-key with ID 0x0007: Wrong premissions for operation. Skipping over ...
All done
11. Save the exported wrapped keys to a secure location.
Now, the YubiHSM is configured with a new wrap-key, and has the same key material.
If you need to restore a YubiHSM, run the command yubihsm-setup restore to import the new wrap key shares, and then the wrapped keys.
Important:
Remember that at this point the older backups that were generated with the previous wrap-key, are no longer useable since the new wrap-key is unable to unwrap the items that were wrapped with the old wrap-key.