YubiHSM 2: Practical Guide

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: Authentication Key, Asymmetric Key and Wrap Key. We start with a fresh YubiHSM 2 configuration and we will proceed in generating a new Authentication Key. 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: Sessions, Domains, Capabilities described in the Concepts Section.

Set Up the Environment

  • Get the latest binaries from SDK download

  • Install all libraries

  • Make sure your device is accessible by the connector. This is accomplished either by running the connector as a superuser or by using an appropriate udev_rule.

Start Up

To physically reset the YubiHSM 2 insert the device while holding the touch sensor for 10 seconds.

Start the connector

yubihsm-connector -d

Check the status of your connector and device by visiting with a browser

Setting Up YubiHSM 2 Connection

Start yubihsm-shell


Connect to YubiHSM 2

yubihsm> connect

Enable keepalive to facilitate usability during first time use (keepalive is enabled by default). Remember that this will consume one session

yubihsm> keepalive on

Enable debug

yubihsm> debug all


Many commands require a Session ID to be specified. To obtain a Session ID use the session open command followed by an Authentication Key ID and a derivation password.

By default the YubiHSM 2 comes with a pre-installed Authentication Key with Object ID 1 and derivation password password. To open a Session with this Authentication Key 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.

Adding a New Authentication Key

Before moving on, make sure you are familiar with concepts of Capabilities and Domains.

For our example we are going to generate an Authentication Key with selected Capabilities and Domains. Learn more about existing key Types here.

yubihsm> put authkey 0 2 yubico 1,2,3 generate-asymmetric-key,export-wrapped,get-pseudo-random,put-wrap-key,import-wrapped,delete-asymmetric-key,sign-ecdsa sign-ecdsa,exportable-under-wrap,export-wrapped,import-wrapped password
export-wrapped allows to create Objects that can perform the Export Wrapped command.
exportable-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 Authentication Keys, besides having regular Capabilities, also have Delegated Capabilities.

List all Objects to see the newly created Authentication Key

yubihsm> list objects 0

Next, let’s start using our newly created Authentication Key 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.

Generate a Key for Signing

We now proceed to generate a new Asymmetric Key. In our example we will use this key to sign some data. We will also export the key under wrap to another YubiHSM, 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 Key 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 exportable-under-wrap,sign-ecdsa ecp256

On success, we will see the message

Generated Asymmetric key 0x0064

signifying that an Asymmetric Key with ID 0x0064 (hexadecimal for 100) was generated.

Prepare to Sign With the New Asymmetric Key

Assuming we have a file called data.txt containing the data we would like to sign, we will sign it using ECDSA with the Asymmetric Key we generated in the previous step

yubihsm> sign ecdsa 1 100 ecdsa-sha256 data.txt

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 sign command.

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.txt
Verified OK

Export Under Wrap

Time to export the Asymmetric Key under wrap to a second YubiHSM 2 (in this example, we will export to the same YubiHSM for convenience)

To do that we need a Wrap Key, which fundamentally is an AES key. We will use the random number generator built into the YubiHSM to generate the 16 bytes needed for an AES-128 key

yubihsm> get random 1 16

The result of this command (the bytes) is considered sensitive data and should be stored safely.

We can now store the Wrap Key on the device with ID 200 by doing

yubihsm> put wrapkey 1 200 label_wrapkey 1,2,3 import-wrapped,export-wrapped sign-ecdsa,exportable-under-wrap 9207653411df91fd36c12faa6886d5c4

Note that for the upcoming export command to be successful, the Delegated Capabilities of the Wrap Key have to include the Capabilities of the Object being exported. Similarly, for the import command to succeed the Delegated Capabilities of the Wrap Key have to include the Capabilities of the Object being imported.

We can now export the Asymmetric Key with ID 100 using the Wrap Key with ID 200 and save it to a file called wrapped_asymmetric.key

yubihsm> get wrapped 1 200 asymmetric-key 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-key

To import the wrapped EC key back into the YubiHSM use

yubihsm> put wrapped 1 200 wrapped_asymmetric.key