.. hsm2-quick-start.rst
.. _hsm2-quick-start-label:
==============================
YubiHSM Quick Start Tutorial
==============================
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 proceed in generating a new Authentication Key. Then we generate an Asymmetric Key for signing purposes. We sign an arbitrary amount of data and verify that our signature is correct. Part of this documentation is to demonstrate how to backup a key on a second YubiHSM 2. We do so by wrapping the Asymmetric Key and re-importing it into the same device.
This tutorial covers:
* :ref:`hsm2-package-label`
* :ref:`hsm2-connect-yubihsm-label`
* :ref:`hsm2-start-manager-label`
* :ref:`hsm2-new-authentication-key-label`
* :ref:`hsm2-generate-key-signing-label`
* :ref:`hsm2-prepare-sign-asymmetric-key-label`
* :ref:`hsm2-export-asymmetric-key-wrap-label`
Before proceeding with this document you should be familiar with concepts such as: ``Sessions``, ``Domains``, ``Capabilities`` described in :ref:`hsm2-intro-core-concepts-label`.
.. Note:: The following code samples have arbitrary line-breaks to prevent them from running off the page.
Physical YubiHSM Care
======================
This section describes general information about packaging, identifying, and caring for your YubiHSM.
.. _hsm2-package-label:
Verify the YubiHSM and Packaging
----------------------------------
The YubiHSM has its own packaging style. Be sure you received the YubiHSM you ordered.
When you receive your YubiHSM, check that the packaging has not been tampered with.
* Check that the YubiHSM arrives in the correct Yubico packaging.
See `YubiKey packaging `_ for images and description of the packaging used for YubiHSM 2 and YubiHSM 2 FIPS.
* Check all the packaging components:
* The security seal on the back of the sleeve is not torn.
.. image:: graphics/HSM2FIPSBox-SleevedR.png
:align: center
:scale: 20%
*YubiHSM packaging with intact security seal*
* The outer box cardboard box is not broken.
* The inner card tray show no signs of wear or tear
.. image:: graphics/DB25-1355-OpenHSMbox_MASTER.png
:align: center
:scale: 20%
*YubiHSM packaging with intact inner card tray*
If you suspect any tampering, `Submit a request `_.
.. _hsm2-usb-pid-label:
YubiHSM ID Numbers
--------------------
Various security protocols and use cases require valid devices identification. For the YubiHSM's USB Product Identifier
(PID), see `How to find the USB Product ID (PID) of your YubiKey `_.
.. _hsm2-cleaning-label:
Care and Cleaning
------------------
YubiHSMs are `IP68-rated `_. This means you can expect the YubiHSM to not allow ingress
of dust up to level 6 and water resistance up to level 8 as defined by the International Electrotechnical Commission,
for ingress protection (IP). See `IP ratings `_.
To clean the YubiHSM, use wipes impregnated with no more than 70% isopropyl alcohol.
.. _hsm2-install-tools-software-label:
Install the YubiHSM 2 Tools and Software
==========================================
To complete the procedures in this guide, install the required YubiHSM 2 tools and software on your system. The YubiHSM 2 SDK is built and provides for the following operating systems: Windows, Linux distributions, and macOS.
.. Tip:: A generic prompt, ``$``, is used in command line examples in this document. Depending on your command line application, your prompt may be different.
The following YubiHSM items of software are used in this guide. They are included as part of the archive file you download. See `YubiHSM2 Releases `_ for most recent platform YubiHSM2 downloads.
1. Unzip the downloaded `archives of the SDK `_ containing the YubiHSM libraries and tools and move the contents to an appropriate location.
2. Complete the step for your operating system.
* On your **Windows** system, run both installers:
* ``yubihsm-manager--x64.msi`` (YubiHSM Manager for Windows)
* ``yubihsm-connector--windows-amd64.msi`` (YubiHSM Connector for Windows)
* On a **Debian**-based system, run the following command:
``$ dpkg -i ./yubihsm-manager_*.deb ./yubihsm-connector_*.deb``
* On a **Redhat**-based system, run the following command:
``$ yum install ./yubihsm-manager-*.rpm ./yubihsm-connector-*.rpm``
* On a **macOS**-based system, use the darwin package.
* ``yubishm2-sdk--darwin-universal.pkg`` (either macOS ARM or AMD chip sets).
* ``yubishm2-sdk--darwin-arm64.pkg`` (macOS ARM chip sets)
* ``yubishm2-sdk--darwin-amd64.pkg`` (macOS AMD chip set)
Double click on the installer package and follow the instructions.
.. _hsm2-connect-yubihsm-label:
Connect to the YubiHSM 2
===========================
The following steps use the ``yubihsm-connector``. Connection can also be made using the direct USB mode which is explained later in this document.
1. Start the connector.
.. code-block:: bash
$ yubihsm-connector --log-level debug
where --
``--log-level debug`` runs the connector in debug mode which may slow down the connector but produces more logs. It is not required for normal mode of operations.
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``. See :ref:`hsm2-backend-usb-permissions-label` for more details.
2. Check the status of your connector and device by using a browser to visit http://127.0.0.1:12345/connector/status.
.. _hsm2-start-manager-label:
Start the YubiHSM Manager
==========================
Most commands can only be send to the YubiHSM 2 within the context of an authenticated session, which requires there
to be an Authentication Key object stored on the device. To establish a session, the Authentication Key Object ID needs
to be specified along with the authentication credential that is associated with that Authentication Key, for example
a password.
By default the YubiHSM 2 comes with a pre-installed Authentication Key with Object ID ``1`` and a derived password
``password``. While it is important to remove or replace this Authentication Key before production deployment, it can
be used for the purposes of this tutorial to establish a session and run commands on the device. See
:ref:`hsm2-concepts-session-label` for more information about sessions and :ref:`hsm2-concepts-objects-label` and
:ref:`hsm2-auth-key-obj` for more information about Authentication Keys.
For this tutorial, we will be using the :ref:`hsm2-tools-manager-label` to interact with the YubiHSM 2 device. The
YubiHSM Manager is a command-line tool that allows you to manage your YubiHSM 2 device. Starting
the manager will automatically open a session to the YubiHSM 2 device and allow you to run commands to manage the
device and its keys.
1. Start the YubiHSM Manager by running the following command in a terminal:
.. code-block:: bash
$ yubihsm-manager
Running ``yubihsm-manager`` without any arguments will attempt to open a session using the default Authentication Key (Object ID ``1``) and will prompt the user for the password.
2. Enter the default password ``password`` to open a session. You should enter the main menu:
.. code-block:: bash
$ yubihsm-manager
* Using authentication key 0x0001
|
> Enter authentication password:
| ********
|
! Warning!! Opening a session using default authentication key and default password. It is strongly recommended to change default credentials
|
> YubiHSM Manager ------------------------------------------------------------------+
| |
| Operations applicable for all objects on the YubiHSM |
| Pressing 'Esc' will always cancel current operation and return to previous menu |
+------------------------------------------------------------------------------------+
|
| * List (List all objects stored on the YubiHSM)
| - Search objects
| - [Asymmetric Key operations]
| - [Symmetric Key operations]
| - [Wrap Key operations]
| - [Authentication Key operations]
| - [Special operations]
| - [Device operations]
| - Exit YubiHSM Manager
Use the arrow keys to navigate the menu and select the desired operation by pressing **Enter**. In multi-choice options, pressing the **Space** key will select or deselect an option. Pressing the **Escape** key will cancel the current operation and return to the previous menu or exit the manager if on the top level menu.
3. Select **List** from the main menu. This will list all the objects currently stored on the YubiHSM 2 device. If this is a brand new YubiHSM, you should see only the default Authentication Key with Object ID ``1`` in the list.
.. code-block:: bash
> YubiHSM Manager > List -----------------------------------------------------------+
| |
| List all objects stored on the YubiHSM |
| Pressing 'Esc' will always cancel current operation and return to previous menu |
+------------------------------------------------------------------------------------+
|
> +------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ID | Type | Label | Algorithm | Domains | Capabilities |
| +--------+-------------------+----------------------------------+--------------------------------+----------------------------------------+------------------------------------------------+
| | 0x0001 | AuthenticationKey | DEFAULT AUTHKEY CHANGE THIS ASAP | "AES128 Yubico Authentication" | 1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16 | get-opaque,put-opaque,put-authentication-key,p |
| | | | | | | ut-asymmetric-key,generate-asymmetric-key,sign |
| | | | | | | pseudo-random,put-mac-key,generate-hmac-key,si |
| | | | | | | gn-hmac,verify-hmac,get-log-entries,sign-ssh-c |
| | | | | | | ertificate,get-template,put-template,reset-dev |
| | | | | | | ice,decrypt-otp,create-otp-aead,randomize-otp- |
| | | | | | | aead,rewrap-from-otp-aead-key,rewrap-to-otp-ae |
| | | | | | | ad-key,sign-attestation-certificate,put-otp-ae |
| | | | | | | ad-key,generate-otp-aead-key,wrap-data,unwrap- |
| | | | | | | data,delete-opaque,delete-authentication-key,d |
| | | | | | | elete-asymmetric-key,delete-wrap-key,delete-hm |
| | | | | | | ac-key,delete-template,delete-otp-aead-key,put |
| | | | | | | -symmetric-key,generate-symmetric-key,delete-s |
| | | | | | | ymmetric-key,decrypt-ecb,encrypt-ecb,decrypt-c |
| | | | | | | bc,encrypt-cbc,put-public-wrap-key,delete-publ |
| | | | | | | ic-wrap-key |
| +--------+-------------------+----------------------------------+--------------------------------+----------------------------------------+------------------------------------------------+
This action lists all objects stored on the YubiHSM 2 device along with their basic properties.
4. To view all properties of a specific object, use the **Search objects** option from the main menu.
a. Select **Search objects**
b. Select **By object ID**
c. Enter Object ID ``1``
This displays all the properties of the default Authentication Key.
.. code-block:: bash
+--------+-------------------+--------------------------------+--------------------------------+----------+----------+--------------------------------+--------------------------------+--------------------------------+
| ID | Type | Label | Algorithm | Sequence | Origin | Domains | Capabilities | Delegated Capabilities |
+--------+-------------------+--------------------------------+--------------------------------+----------+----------+--------------------------------+--------------------------------+--------------------------------+
| 0x0001 | AuthenticationKey | DEFAULT AUTHKEY CHANGE THIS | "AES128 Yubico Authentication" | 0 | Imported | 1,2,3,4,5,6,7,8,9,10,11,12,13, | get-opaque,put-opaque,put-auth | get-opaque,put-opaque,put-auth |
| | | ASAP | | | | 14,15,16 | entication-key,put-asymmetric- | entication-key,put-asymmetric- |
| | | | | | | | key,generate-asymmetric-key,si | key,generate-asymmetric-key,si |
| | | | | | | | gn-pkcs,sign-pss,sign-ecdsa,si | gn-pkcs,sign-pss,sign-ecdsa,si |
| | | | | | | | gn-eddsa,decrypt-pkcs,decrypt- | gn-eddsa,decrypt-pkcs,decrypt- |
| | | | | | | | oaep,derive-ecdh,export-wrappe | oaep,derive-ecdh,export-wrappe |
| | | | | | | | d,import-wrapped,put-wrap-key, | d,import-wrapped,put-wrap-key, |
| | | | | | | | generate-wrap-key,exportable-u | generate-wrap-key,exportable-u |
| | | | | | | | nder-wrap,set-option,get-optio | nder-wrap,set-option,get-optio |
| | | | | | | | n,get-pseudo-random,put-mac-ke | n,get-pseudo-random,put-mac-ke |
| | | | | | | | y,generate-hmac-key,sign-hmac, | y,generate-hmac-key,sign-hmac, |
| | | | | | | | verify-hmac,get-log-entries,si | verify-hmac,get-log-entries,si |
| | | | | | | | gn-ssh-certificate,get-templat | gn-ssh-certificate,get-templat |
| | | | | | | | e,put-template,reset-device,de | e,put-template,reset-device,de |
| | | | | | | | crypt-otp,create-otp-aead,rand | crypt-otp,create-otp-aead,rand |
| | | | | | | | omize-otp-aead,rewrap-from-otp | omize-otp-aead,rewrap-from-otp |
| | | | | | | | -aead-key,rewrap-to-otp-aead-k | -aead-key,rewrap-to-otp-aead-k |
| | | | | | | | ey,sign-attestation-certificat | ey,sign-attestation-certificat |
| | | | | | | | e,put-otp-aead-key,generate-ot | e,put-otp-aead-key,generate-ot |
| | | | | | | | p-aead-key,wrap-data,unwrap-da | p-aead-key,wrap-data,unwrap-da |
| | | | | | | | ta,delete-opaque,delete-authen | ta,delete-opaque,delete-authen |
| | | | | | | | tication-key,delete-asymmetric | tication-key,delete-asymmetric |
| | | | | | | | -key,delete-wrap-key,delete-hm | -key,delete-wrap-key,delete-hm |
| | | | | | | | ac-key,delete-template,delete- | ac-key,delete-template,delete- |
| | | | | | | | otp-aead-key,put-symmetric-key | otp-aead-key,put-symmetric-key |
| | | | | | | | ,generate-symmetric-key,delete | ,generate-symmetric-key,delete |
| | | | | | | | -symmetric-key,decrypt-ecb,enc | -symmetric-key,decrypt-ecb,enc |
| | | | | | | | rypt-ecb,decrypt-cbc,encrypt-c | rypt-ecb,decrypt-cbc,encrypt-c |
| | | | | | | | bc,put-public-wrap-key,delete- | bc,put-public-wrap-key,delete- |
| | | | | | | | public-wrap-key | public-wrap-key |
+--------+-------------------+--------------------------------+--------------------------------+----------+----------+--------------------------------+--------------------------------+--------------------------------+
.. _hsm2-new-authentication-key-label:
Add a New Authentication Key
====================================
Before moving on, make sure you are familiar with concepts of :ref:`hsm2-concepts-capability-label` and :ref:`hsm2-concepts-domain-label`
1. For our example we are going to generate an Authentication Key with selected Capabilities and Domains. Learn more about existing key Types at :ref:`hsm2-concepts-objects-label`.
a. From the main menu, select **[Authentication Key operations]**.
b. Select **Setup custom user**
c. Enter Object ID **2**
d. Enter label **student**
e. Select Domains **1**, **2**, and **3**
f. Select the Capabilities:
* **Delete Asymmetric Key Objects**
* **Export other Objects under wrap**
* **Extract random bytes**
* **Generate Asymmetric Key Objects**
* **Import Wrap Key Objects**
* **Import wrapped Objects**
* **Sign data using ECDSA**
g. Select Delegated Capabilities:
* **Export other Objects under wrap**
* **Exportable under wrap**
* **Import wrapped Objects**
* **Sign data using ECDSA**
.. Important::
While the list of Capabilities and Delegated Capabilities to select from are the same, they are distinct in that Capabilities specify operation the Authentication Key is permitted to perform, while Delegated Capabilities specify operations that the Authentication Key can grant to other Objects that it creates.
.. Important::
**Export other Objects under wrap** allows the creation of Objects that can perform export of other objects in encrypted form.
**Exportable under wrap** allows the creation of Objects that can be exported in encrypted form.
h. Select **Password Derived**
i. Enter password for the new Authentication Key, ``foo123``
j. Confirm the password by entering ``foo123`` again. A table with all selected options is displayed for confirmation.
k. Confirm the creation of the new Authentication Key by selecting **Yes**.
On success, the following message is displayed before returning to menu:
.. code-block:: bash
Created new authentication key with ID 0x0002
This means that a new Authentication Key with Object ID ``0x0002`` (hexadecimal for 2) was created and stored on the device.
2. List all Objects to see the newly created Authentication Key.
Select **List** from the presented menu
A table containing both the default Authentication Key and the new Authentication Key is displayed.
3. Next, let's start using our newly created Authentication Key to establish an encrypted Session.
a. Exit the YubiHSM Manager by Selecting **Exit YubiHSM Manager** from the presented menu.
b. In the terminal, start the YubiHSM Manager again with the command ``yubihsm-manager --authkey 2``. This will attempt to open a session using the Authentication Key with Object ID ``2`` and will prompt the user for the password.
c. Enter the password ``foo123`` to open a session. You should enter the main menu again, but this time you are authenticated with the new Authentication Key.
.. _hsm2-generate-key-signing-label:
Generate an Asymmetric Key Object 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.
1. From the main menu, select **[Asymmetric Key operations]**.
2. Select **Generate**
3. Select **EC SEC-P256**
4. Enter Object ID **100**
5. Enter label **label_ecdsa_sign**
6. Select Domains **All Domains**
.. Note:: Note that this time, only Domains 1, 2, and 3 are presented as options. This is because an object cannot be created with access to Domains that the Authentication Key used to create it does not have access to.
7. Select the Capabilities **All Capabilities**:
.. Note:: Note that the Capabilities presented this time are only a subset of all existing Capabilities. This is because an object cannot be created with Capabilities that the Authentication Key used to create it is not authorized to grant. In other words, a new object can only be created with *Capabilities* that the Authentication Key has in its *Delegated Capabilities*
8. A table with all selected options is displayed for confirmation.
.. Note:: Note that this time, we are not selecting any Delegated Capabilities. This is because an Asymmetric Key cannot create any new objects on the YubiHSM and thus does not grant any Capabilities to other objects.
Confirm the creation of the new Asymmetric Key by selecting **Yes**.
On success, the following message is displayed before returning to menu:ยง
.. code-block:: bash
Generated object of type asymmetric-key and ID 0x0064 on the YubiHSM
This signifies that an Asymmetric Key with ID ``0x0064`` (hexadecimal for 100) was generated.
9. List Asymmetric Objects to see the newly created Asymmetric Key.
Select **List** from the presented menu
A table containing the new Authentication Key is displayed.
.. Note:: Not that in this table, only Asymmetric Keys are listed. This is because the List operation was performed within the context of **[Asymmetric Key operations]** menu. To list all objects currently on the device: Press **Esc** to return to the main menu then select **List** from there.
.. _hsm2-prepare-sign-asymmetric-key-label:
Sign With the New Asymmetric Key
=================================
1. 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.
a. From the main menu, select **[Asymmetric Key operations]**.
b. Select **Sign**
c. Enter path to ``data.txt``
d. Select the signing key ``0x0064``
e. Select **ECDSA with SHA-256**
By default the output is printed to the standard output and consists of the Hex-encoded signature like the one below.
.. code-block:: bash
304402206c0401d23d712a06615ab8471fbb7561a05d30eeae54803c64bad31657ae3ef20220099901d4e3bc4b317d412ffc38f718844aa7818b3e586decb5b5c02c24ed7a63
f. When questioned about writing the signature to a file, select **Yes**.
g. Press **Enter** to select the default file for the signature.
On success, the following message is displayed before returning to menu:
.. code-block:: bash
Wrote file ./data.sig
2. Next, we will extract the public key from the Asymmetric Key on the device and write it to a file so that we can use it to verify the signature we just created.
a. From the menu, select **Get Public Key**.
b. Select the signing key ``0x0064``
The public key is displayed in Base64 format.
c. When questioned about writing the public key to a file, select **Yes**.
g. Press **Enter** to select the default file for the public key.
On success, the following message is displayed before returning to menu:
.. code-block:: bash
Wrote file ./0x0064.pubkey.pem
3. We are going to use OpenSSL for the verification process, which is done outside the YubiHSM Manager.
a. From the menu, select **Exit YubiHSM Manager** to exit the manager.
b. Use the following command to verify the signature using OpenSSL. You should get the output ``Verified OK`` if the signature is valid.
.. code-block:: bash
$ openssl dgst -sha256 -signature data.sig -verify 0x0064.pubkey.pem data.txt
Verified OK
.. _hsm2-export-asymmetric-key-wrap-label:
Export an Asymmetric Key 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).
1. To do that we need a Wrap Key, which fundamentally is an AES key. We use the random number generator built into the YubiHSM to generate the 16 bytes needed for an AES-128 key.
a. In the terminal, start the YubiHSM Manager again with the command ``yubihsm-manager --authkey 2`` and enter the password ``foo123`` when prompted
b. From the main menu, select **[Wrap Key operations]**.
c. Select **Generate pseudo random number**
d. Enter number of bytes to generate, **16**. A 16 bytes string is displayed in Hex format.
e. From the menu, select **Import Wrap Key**
f. When questioned about recreating from shares, select **No**.
g. Enter the 16 bytes string from step **1d** as the key material for the new Wrap Key.
h. Enter **200** as the Object ID for the new Wrap Key.
i. Enter label **label_wrapkey**
j. Select Domains **1**, **2**, and **3**
k. Select the Capabilities:
* **Export other Objects under wrap**
* **Import wrapped Objects**
l. Select Delegated Capabilities:
* **Exportable under wrap**
* **Sign data using ECDSA**
.. Note::
For both exporting and importing an object under wrap, the Delegated Capabilities of the Wrap Key have to include all the Capabilities of the Object being exported/imported.
m. A table with all selected options is displayed for confirmation.
Confirm the creation of the new Wrap Key by selecting **Yes**.
On success, the following message is displayed:
.. code-block:: bash
Imported wrap-key object with ID 0x00c8 into the YubiHSM
n. When questioned about splitting the wrap key into shares, select **No**. You will now return to the menu.
2. We can now export the Asymmetric Key with ID ``100`` using the Wrap Key with ID ``200`` and save it to a file called ``0x0064-asymmetric-key.yhw``.
a. From the menu, select **Export objects under wrap**.
b. Select the wrapkey with ID ``0x00c8`` (``200`` in Hex)
c. Select the asymmetric key with ID ``0x0064`` (``100`` in Hex) to be exported by pressing the **Space** key and then **Enter**. Outside this tutorial, you can select multiple keys.
d. Press **Enter** to select the current directory as the the location for the file containing the wrapped object.
On success, the following message is displayed before returning to menu:
.. code-block:: bash
Wrote file ./0x0064-asymmetric-key.yhw
3. We are going to re-import the Asymmetric Key on the same device so we need to first delete the existing one.
a. Press **ESC** to return to the main menu
b. Select **[Asymmetric Key operations]**.
c. Select **Delete**
d. Select the asymmetric key with ID ``0x0064`` to be deleted by pressing the **Space** key and then **Enter**.
A confirmation prompt is displayed.
e. Confirm the deletion by selecting **Yes**.
On success, the following message is displayed before returning to menu:
.. code-block:: bash
Successfully deleted asymmetric-key object with ID 0x0064 from the YubiHSM
4. We now import the wrapped EC key back into the YubiHSM using the same Wrap Key.
a. Press **ESC** to return to the main menu
b. Select **[Wrap Key operations]**.
c. From the menu, select **Import wrapped object**.
d. Enter the path to the wrapped EC key, **./0x0064-asymmetric-key.yhw**.
e. Select the wrapkey with ID ``0x00c8``
On success, the following message is displayed before returning to menu:
.. code-block:: bash
Successfully imported object asymmetric-key, with ID 0x0064