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 Secret Sharing requires an authentication key with certain capabilities, which is not present if you have if you follow the YubiHSM 2 initial provisioning and 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 2, refer to YubiHSM 2 backup and restore.
Procedure
1. Open 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 YubiHSM 2 contents through 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 2 according to Resetting device to factory settings
5. Restore the keys to the YubiHSM 2 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 according to Configuring the primary YubiHSM 2 device.
At steps 1-5, use the same values as for the existing YubiHSM 2.
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 2 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 2 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 2 is configured with a new wrap-key, and has the same key material.
If you need to restore a YubiHSM 2, 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 usable since the new wrap key is unable to unwrap the items that were wrapped with the old wrap key.