.. hsm2-quick-start.rst .. _hsm2-quick-start-label: ===================== 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: * Basic YubiHSM 2 setup * Connecting to YubiHSM 2 * Generating an Authkey on the device * Generating an Asymmetric Object * Generating a Wrapkey * Exporting/Importing an Object under wrap Before proceeding with this document you should be familiar with concepts such as: ``Sessions``, ``Domains``, ``Capabilities`` described in the :ref:`hsm2-core-concepts-label` section. .. Note:: The following code samples have arbitrary line-breaks to prevent them from running off the page. Set Up the Environment ======================= :Step 1: Get the latest binaries from SDK download `YubiHSM2/Releases `_. :Step 2: Install all libraries. :Step 3: 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. The following steps use the yubihsm-connector. Connection can also be made using the direct USB mode which is explained later in this document. :Step 1: Start the connector. .. code-block:: bash $ yubihsm-connector -d where -- ``-d`` runs the connector in debug mode which may slow down the connector. It is not required for normal mode of operations. :Step 2: Check the status of your connector and device by using a browser to visit http://127.0.0.1:12345/connector/status. Set Up YubiHSM 2 Connection ============================ :Step 1: Start yubihsm-shell. .. code-block:: bash $ yubihsm-shell :Step 2: Connect to YubiHSM 2. .. code-block:: bash $ yubihsm> connect Sessions ========== 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``. Open ===== To open a Session with this Authentication Key use: .. code-block:: bash yubihsm> session open 1 password Created session 0 The Session ID is the number found in the line directly below a ``session open`` command. where-- ``0`` Is the Session ID. This value is used to address the newly created Session. ``1`` is the object ID of the pre-installed Authentication Key. ``password`` is the password of the pre-installed Authentication Key. Close ====== To close a Session use the command ``session close`` followed by the Session ID: .. code-block:: bash yubihsm> session close 0 where-- ``0`` Is the Session ID. List ===== To list the objects in the device use: .. code-block:: bash yubihsm> list objects 0 where-- ``0`` Is the Session ID. .. Note:: If you have closed Session ``0``, the above command will not work. In that situation, open a new Session 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 :ref:`hsm2-concepts-capability-label` and :ref:`hsm2-concepts-domain-label` :Step 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`. .. code-block:: bash 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 where-- ``put authkey`` is the command to create a new authentication key. ``0`` is the session ID. ``2`` is the ObjectID of the new authentication key. ``yubico`` is the label of the new authentication key. ``1,2,3`` is the domain where the new authentication key will perate within. ``generate-asymmetric-key, export-wrapped,get-pseudo-random,put-wrap-key,import-wrapped,delete-asymmetric-key,sign-ecdsa`` are the capabilities for the new authentication key. ``sign-ecdsa,exportable-under-wrap,export-wrapped,import-wrapped`` the delegated capabilities for the new authentication key. ``password`` is the password used to derive the new authentication key. This is the password you specify when opening a session with the YubiHSM using this authentication key. .. Important:: ``export-wrapped`` allows the creation of Objects that can perform the :ref:`hsm2-cmd-export-wrapped-label` command. ``exportable-under-wrap`` allows the creation of Objects that can be exported under wrap. .. Note:: The command above has two distinct sets of Capabilities, separated by a space. This is because Authentication Keys, in addition to having regular Capabilities, also have :ref:`hsm2-concepts-capability-label`. :Step 2: List all Objects to see the newly created Authentication Key. .. code-block:: bash yubihsm> list objects 0 where-- ``0`` the Session ID used for the open session. :Step 3: Next, let’s start using our newly created Authentication Key to establish an encrypted Session. .. code-block:: bash yubihsm> session open 2 password Created session 1 where-- ``1`` is the Session ID assigned to the new Session. 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. ``2`` is the ObjectID of the authentication key used to open the session. ``password`` is the password of the authentication key used to open the session. 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: .. code-block:: bash yubihsm> generate asymmetric 1 100 label_ecdsa_sign 1,2,3 exportable-under-wrap,sign-ecdsa ecp256 where-- ``generate`` is YubiHSM shell command. ``asymmetric`` is the key type to be generated. ``1`` is the session ID. ``100`` is the key ID. ``label_ecdsa_sign`` is the label for the new key object. ``1,2,3`` are the domains where the new key will be accessible. ``exportable-under-wrap`` allows this key to be exported under wrap. ``sign-ecdsa`` is allows this key to be used to perform ECDSA signature. ``ecp256`` specifies NIST P-256 curve for the key. On success, we will see the message: .. code-block:: bash Generated Asymmetric key 0x0064 This signifies that an Asymmetric Key with ID ``0x0064`` (hexadecimal for 100) was generated. Prepare to Sign With the New Asymmetric Key ============================================ :Step 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. .. code-block:: bash yubihsm> sign ecdsa 1 100 ecdsa-sha256 data.txt where-- ``1`` is the Session ID. ``100`` is the key ID. By default the output is printed to the standard output and consists of a Base64-encoded signature like the one below. .. code-block:: bash MEUCIQDrBqS04LN5YdyWGiD4iaEjfl1dn+W4cl97uM MXDpoaiQIgEBe/G/FgP4cumnO3K2XWToAnPvnuVDOnqHPiuUS0q5g= :Step 2: 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. .. code-block:: bash $ echo MEUCIQDrBqS04LN5YdyWGiD4iaEjfl1dn+W4cl97uM MXDpoaiQIgEBe/G/FgP4cumnO3K2XWToAnPvnuVDOnqHPiuUS 0q5g= >signature.b64 :Step 3: 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. .. code-block:: bash yubihsm> get pubkey 1 100 asymmetric_key.pub :Step 4: 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: .. code-block:: bash $ base64 -d signature.b64 >signature.bin :Step 5: It is now possible to verify the signature with OpenSSL. .. code-block:: bash $ 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). :Step 1: 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. .. code-block:: bash yubihsm> get random 1 16 9207653411df91fd36c12faa6886d5c4 .. Important:: The result of this command (the bytes) is considered extremely sensitive data and should be stored safely, and preferably, separate from any production environment. :Step 2: We can now store the Wrap Key on the device with ID 200 by doing: .. code-block:: bash yubihsm> put wrapkey 1 200 label_wrapkey 1,2,3 import-wrapped,export-wrapped sign-ecdsa, exportable-under-wrap 9207653411df91fd36c12faa6886d5c4 .. Note:: 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. :Step 3: 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``. .. code-block:: bash yubihsm> get wrapped 1 200 asymmetric-key 100 wrapped_asymmetric.key :Step 4: We are going to re-import the Asymmetric Key on the same device so we need to first delete the existing one. .. code-block:: bash yubihsm> delete 1 100 asymmetric-key :Step 5: To import the wrapped EC key back into the YubiHSM use: .. code-block:: bash yubihsm> put wrapped 1 200 wrapped_asymmetric.key