This tutorial will cover:
Basic YubiHSM 2 setup
Connecting to YubiHSM 2
Generating an Authkey on the device
Generating an Asymmetric Object
Generate a Wrapkey
Exporting/Importing an Object under wrap
The purpose of this tutorial is to demonstrate basic functionalities of different key types, Authkey, Asymmetric and Wrapkeys. We start with a fresh YubiHSM 2 configuration and we will proceed in generating a new Authkey. Then we generate an Asymmetric key for signing purposes. We will sign an arbitrary amount of data and verify that our signature is correct. Part of this documentation is to demonstrate how to back up a key on a second YubiHSM 2. We will do so by wrapping the Asymmetric key and re-importing it into the same device.
Before reading this document you should be familiar with concepts such as:
Capabilities described in the Concepts Section.
To physically reset the YubiHSM 2 insert the device while holding the touch sensor for 10 seconds.
Start the connector
Check the status of your connector and device by visiting
http://127.0.0.1:12345/connector/status with a browser
Connect to YubiHSM2
Set keepalive active to facilitate usability during first time use. Remember that this will consume one session
yubihsm> keepalive 25
yubihsm> debug all
Many commands require for a Session ID to be specified. To obtain a Session ID use the
session open command followed by an Authkey ID and a derivation password.
By default the YubiHSM 2 comes with a pre-installed Authkey with Object ID
1 and derivation password
password. To open a Session with this Authkey use
yubihsm> session open 1 password Created session 0
The Session ID is the number found in the line directly below a
session open command. In the example above the Session ID is
0. This value will be used to address the newly created Session.
To close a Session use the command
session close followed by the Session ID
yubihsm> session close 0
To list the objects in the device use
yubihsm> list objects 0
Note that if you have closed Session 0, the above command will not work. Open a new Session in that case and use the new Session ID in the command above.
For our example we are going to generate an Authkey with selected Capabilities and Domains. Learn more about existing key Types here.
yubihsm> put authkey 0 2 yubico 1,2,3 asymmetric_gen,export_wrapped,get_randomness,put_wrapkey,import_wrapped,delete_asymmetric,asymmetric_sign_ecdsa asymmetric_sign_ecdsa,export_under_wrap,export_wrapped,import_wrapped password
|export_wrapped allows to create Objects that can perform the export_wrap command.
export_under_wrap allows to create Objects that can be exported under wrap.
Note how the command above has two distinct sets of Capabilities, separated by a space. This is because Authkey Objects, besides having regular Capabilities, also have Delegated Capabilities.
List all Objects to see the newly created Authkey
yubihsm> list objects 0
Next, let’s start using our newly created Authkey to establish a Session
yubihsm> session open 2 password Created session 1
The new Session has been assigned Session ID
1. We will use this Session ID for most of the commands below.
If at any time the Session is closed or expires because of inactivity, open a new one and use the correct Session ID.
We now proceed to generate a new key Type: Asymmetric. In our example we will use this key to sign some data. We will also export the key under wrap to another HSM, for backup purposes.
Specifically we will ask the device to generate an Asymmetric key with ID
100 and a given set of Domains and Capabilities. We will also specify the kind of Asymmetric Object that we would like to generate, an EC key using the NIST P-256 curve in this case.
The command is
yubihsm> generate asymmetric 1 100 label_ecdsa_sign 1,2,3 export_under_wrap,asymmetric_sign_ecdsa ecp256
On success, we will see the message
Generated Asymmetric key 0x0064
signifying that an Asymmetric Object with ID
0x0064 (hexadecimal for 100) was generated.
Assuming we have a file called
data.txt containing the data we would like to sign, and a file called
data.sha that contains the SHA-256 message digest of the data, we will sign using ECDSA with the Asymmetric key we generated in the previous step
yubihsm> sign ecdsa 1 100 ecdsa-sha256 data.sha
by default the output is printed to the standard output and consists of a Base64-encoded signature like the one below
This behavior can be changed by using the
set outformat and
set informat commands, and by specifying an additional output parameter to the
For now we will store the signature as it is in a temporary file so that we will be able to verify it later
echo MEUCIQDrBqS04LN5YdyWGiD4iaEjfl1dn+W4cl97uMMXDpoaiQIgEBe/G/FgP4cumnO3K2XWToAnPvnuVDOnqHPiuUS0q5g= >signature.b64
Next, we will extract the public key from the Asymmetric key on the device and write it to the file
asymmetric_key.pub, so that we can use it to verify the signature we just created
yubihsm> get pubkey 1 100 asymmetric_key.pub
We are going to use OpenSSL for the verification process. Since the signature that we created before is in Base64 format, we need to convert it first. Do so with
base64 -d signature.b64 >signature.bin
It is now possible to verify the signature with OpenSSL
openssl dgst -sha256 -signature signature.bin -verify asymmetric_key.pub data.sha Verified OK
Time to export the Asymmetric key under wrap to a second YubiHSM 2 (in this example, we will export to the same HSM for convenience)
To do that we need a Wrapkey, which fundamentally is an AES key. We will use the random number generator built into the YubiHSM 2 to generate the 16 bytes needed for an AES-128 key
yubihsm> get random 1 16 9207653411df91fd36c12faa6886d5c4
The result of this command (the bytes) is considered sensitive data and should be stored safely.
We can now store the Wrapkey on the device with ID
200 by doing
yubihsm> put wrapkey 1 200 label_wrapkey 1,2,3 import_wrapped,export_wrapped asymmetric_sign_ecdsa,export_under_wrap 9207653411df91fd36c12faa6886d5c4
Note that for the upcoming export command to be successful, the Delegated Capabilities of the Wrapkey have to include the Capabilities of the Object being exported. Similarly for the import command to succeed the Delegated Capabilities of the Wrapkey have to include the Capabilities of the Object being imported.
We can now export the Asymmetric key with ID
100 using the Wrapkey with ID
200 and save it to a file called
yubihsm> get wrapped 1 200 asymmetric 100 wrapped_asymmetric.key
We are going to re-import the Asymmetric key on the same device so we need to first delete the existing one
yubihsm> delete 1 100 asymmetric
To import the wrapped EC key back into the YubiHSM 2 use
yubihsm> put wrapped 1 200 wrapped_asymmetric.key