.. hsm2-sdk-tools-libraries.rst

.. _hsm2-sdk-tools-libraries-label:


===================================
YubiHSM 2 SDK Tools And Libraries
===================================

.. _hsm2-setup-tool-label:

YubiHSM 2 Setup Tool
=====================

The SDK ships with a tool called `yubihsm-setup <https://developers.yubico.com/yubihsm-setup/>`_ that helps with setting up a device for specific use cases. The tool assumes familiarity with the key concepts of YubiHSM such as :ref:`hsm2-concepts-domain-label`,
:ref:`hsm2-concepts-capability-label` and :ref:`hsm2-concepts-objectid-label`. It currently supports the following:

 * 	setup for KSP/ADCS and EJBCA;

 * 	restoring a previous configuration

 * 	resetting the device to factory defaults

 * 	exporting all existing objects

The tool is based around the concept of secret-sharing. When setting up Objects, those are exported with a freshly created Wrap Key. The key is never stored on disk, but rather it is printed on the screen as shares. The key concepts here are:

 *	The number of shares, which is the number of parts the key should be divided into.

 *	The security threshold, which is the minimum number of shares required to reconstruct the Wrap Key.

Besides splitting the Wrap Key into shares, the tool (by default) also exports under wrap all the newly created objects and saves them in the current directory. This can be used at a later time to “clone” or recover a device. This operation can be performed either with ``yubihsm-setup`` or manually if the Wrap Key is known.

By default, the Authentication Key used to establish a Session with the device is also normally deleted at the end of the process.

Default behavior can be altered with command line options. For more information, consult the tool’s help.

Setup for EJBCA
----------------

When setting up the device for use by EJBCA, the setup tool will also generate an asymmetric keypair and an X509 certificate suitable for use as a CA key. The setup tool can be re-run as many times as the number of asymmetric keys to be generated since each run will produce only one keypair and one corresponding X509 certificate.

.. Note::
   Using the ``--no-new-authkey`` flag will prevent generation of a new Wrap Key and a new Authentication Key.

How It Works
-------------

For the JAVA implementation, a keypair can be used to perform PKCS#11 operations only if the key and its corresponding X509 certificate are stored under the same ID on the device (the value of their CKA_ID attributes is the same). To store them under the same ID, run the YubiHSM 2 Setup tool with the ``ejbca`` subcommand:

 1.	Generate an Asymmetric Key on the YubiHSM 2.

 2.	Generate an attestation certificate for the asymmetric key and import it into the YubiHSM 2 under the same ID as the Asymmetric Key.

The attestation certificate stored on the YubiHSM 2 is, in fact, only a placeholder certificate for the public key. It is never used by EJBCA because EJBCA stores the CAs’ certificates in a dedicated database.

.. _hsm2-shell-label:

YubiHSM Shell
================

The `yubihsm-shell <https://developers.yubico.com/yubihsm-shell/yubihsm-shell.html>`_ is the administrative and testing tool you can use to interact with and configure the YubiHSM 2 device. All the commands supported by YubiHSM 2 :ref:`hsm2-cmd-reference-label` can be issued to YubiHSM 2 using YubiHSM 2 Shell.

The Shell can be invoked in two different ways: interactively, or as a command line tool useful for scripting.

Additional information on the various commands can be obtained with the ``help`` command in interactive mode or by referring to the ``--help`` argument for the command line mode.

Examples of commands can also be found in the :ref:`hsm2-cmd-reference-label` reference.

YubiHSM Shell Command Syntax
-------------------------------

Commands and subcommands require specific arguments to work. The Shell will return an error message if the command syntax is incorrect, pointing at the first invalid argument.

Arguments have different types. In interactive mode pre-defined values for command types can be tab-completed (Tab Completion does not work on Windows). Command arguments are explained in the table below.

.. table::

  +-----+-----------------+----------------------------------------------------+
  | Arg | Type            | Description                                        |
  +=====+=================+====================================================+
  | A   | Algorithm       | An algorithm in string form (ex: ecp256)           |
  +-----+-----------------+----------------------------------------------------+
  | B   | Byte            | A generic (hex or dec) 8-bit unsigned number       |
  +-----+-----------------+----------------------------------------------------+
  | C   | capabilities    || A list of Capabilities in either form:            |
  |     |                 || hex (ex: 0xffffffffffffffff) or                   |
  |     |                 || string (ex: sign-pkcs,sign-pss, get-log-entries)  |
  +-----+-----------------+----------------------------------------------------+
  | D   | Domains         || A list of Domains, either in hex (ex: 0xffff) or  |
  |     |                 || string form (ex: 3,5,14)                          |
  +-----+-----------------+----------------------------------------------------+
  | I   | Format          | A format specifier in string form (ex: base64)     |
  +-----+-----------------+----------------------------------------------------+
  | I   | input data      | Input data, generally defaults to standard input   |
  +-----+-----------------+----------------------------------------------------+
  | U   | Number          | A generic (hex or dec) unsigned number             |
  +-----+-----------------+----------------------------------------------------+
  | O   | Option          || A device-global option in string form             |
  |     |                 || (ex: force-audit)                                 |
  +-----+-----------------+----------------------------------------------------+
  | F   | output filename || Output file name, generally defaults to standard  |
  |     |                 || output                                            |
  +-----+-----------------+----------------------------------------------------+
  | E   | Session         | The ID of an already-established Session           |
  +-----+-----------------+----------------------------------------------------+
  | S   | String          || A generic string (use quotes for strings          |
  |     |                 || including white spaces)                           |
  +-----+-----------------+----------------------------------------------------+
  | T   | Type            | An Object Type in string form (ex: Asymmetric)     |
  +-----+-----------------+----------------------------------------------------+
  | W   | Word            | A generic (hex or dec) 16-bit unsigned number      |
  +-----+-----------------+----------------------------------------------------+


Different commands have different default formats. These can be listed by invoking ``help`` on a specific command. For example, the ``help sign`` will display the following message:


.. code-block:: bash

  pss           Sign data using RSASSA-PSS (default input format: binary)
                e:session,w:key_id,a:algorithm,i:data=-,F:out=-


As can be seen, the input format is binary. Additionally, arguments to a command that have ``=-`` after their type and name (like ``i:data`` and ``F:out`` in the example above), use the standard input or standard output by default for reading data.

Different levels of debug output can be enabled by using the ``-v`` flag in command line mode, or by issuing the ``debug LEVEL`` command in interactive mode, where LEVEL is one of ``all``, ``crypto``, ``error``, ``info``, ``intermediate``, ``none``, or ``raw``.

The following is a list of supported yubihsm-shell commands and their formats.


  **Blink Device --** Blinks the LED of the device to identify it.

     *Interactive mode*

     .. code-block:: bash

        $ blink <session> <seconds=10>

     *Command line mode*

     .. code-block:: bash

        $ yubihsm-shell -a blink-device [--duration <seconds=10>]

  **Change Authentication Key --**  Replaces the Authentication Key used to establish the current Session.

     *Interactive mode*

     .. code-block:: bash

        $ change authkey <session> <key_id> <password=->

  **Close Session --** Closes the current session and releases it for re-use.

     *Interactive mode*

     .. code-block:: bash

         $ session close <session>

  **Create Otp Aead --** Creates a Yubico OTP AEAD using the provided data.

     *Interactive mode*

     .. code-block:: bash

        $ otp aead_create <session> <key_id> <key> <private_id> <aead>


  **Decrypt AES CBC	--** Decrypt data in AES CBC mode.

     *Interactive mode*

     .. code-block:: bash

        $ decrypt aescbc  <session> <key_id> <iv> <data=->

     *Command line mode*

     .. code-block:: bash

        $ yubihsm-shell -a decrypt-aescbc -i <key_id> --iv <iv> --in <data>


  **Decrypt AES ECB --** Decrypt data in AES ECB mode.

     *Interactive mode*

     .. code-block:: bash

        $ decrypt aesecb  <session> <key_id> <data=->

     *Command line mode*

     .. code-block:: bash

        $ yubihsm-shell -a decrypt-aesecb -i <key_id> --in <data>


  **Decrypt Oaep --** Decrypts data encrypted with RSA-OAEP.

     *Interactive mode*

     .. code-block:: bash

        $ decrypt oaep <session> <key_id> <algorithm> <in_data=-> <label=>

     *Command line mode*

     .. code-block:: bash

        $ yubihsm-shell –a decrypt-oaep -i <key_id> -A <decrypt_algorithm> [--in <in_data> -l <oaep_label>]

  **Decrypt Otp --** Decrypts a Yubico OTP with an AEAD and returns counters and timer information (default input format in binary).

     *Interactive mode*

     .. code-block:: bash

        $ otp decrypt <session> <key_id> <otp> <aead>

  **Decrypt Pkcs1 --** Decrypts data encrypted with RSA-PKCS#1v1.5.

     *Interactive mode*

     .. code-block:: bash

        decrypt pkcs1v1_5 <session> <key_id> data=->``

     *Command line mode*

     .. code-block:: bash

        $ yubihsm-shell -a decrypt-pkcs1v15 -i <key_id> [--in <data>]

  **Delete Object --** Deletes an object in the device.

     *Interactive mode*

     .. code-block:: bash

        $ delete <session> <object_id> <type>

     *Command line mode*

     .. code-block:: bash

        $ yubihsm-shell -a delete-object -i <object_id> -t <type>``

  **Derive Ecdh  --** Performs an ECDH key exchange with the private key in the device.

     *Interactive mode*

     .. code-block:: bash

        $ derive ecdh <session> <key_id> <public_key=->

     *Command line mode*

     .. code-block:: bash

        $ yubihsm-shell -a derive-ecdh -i <key_id> [--in <public_key>]

  **Encrypt AES CBC --** Encrypt data in AES CBC mode.

  	 *Interactive mode*

     .. code-block:: bash

        $ encrypt aescbc  <session> <key_id> <iv> <data=->

     *Command line mode*

     .. code-block:: bash

        $ yubihsm-shell -a encrypt-aescbc -i <key_id> --iv <iv> --in <data>

  **Encrypt AES ECB	--** Encrypt data in AES ECB mode.

     *Interactive mode*

     .. code-block:: bash

        $ encrypt aesecb  <session> <key_id> <data=->

     *Command line mode*

     .. code-block:: bash

        $ yubihsm-shell -a encrypt-aesecb -i <key_id> --in <data>

  **Export Wrapped  --** Retrieves an object under wrap from the device. The Object is encrypted using AES-CCM with a 16 bytes MAC and a 13 bytes nonce.

     *Interactive mode*

     .. code-block:: bash

        $ get wrapped <session> <wrapkey_id> <type> <object_id> <file=->

     *Command line mode*

     .. code-block:: bash

        $ yubihsm-shell -a get-wrapped --wrap-id <wrapkey_id> -t <type> -i <object_id> [--out <file>]

  **Generate Asymmetric Key --** Generates an Asymmetric Key in the device.

     *Interactive mode*

     .. code-block:: bash

        $ generate asymmetric session> <object_id> <label> <domains> <capabilities> <algorithm>

     *Command line mode*

     .. code-block:: bash

        $ yubihsm-shell -a generate-asymmetric-key -i <object_id> -l <label> -d <domains> -c <capabilities> -A <algorithm>

  **Generate Hmac Key --** Generates an HMAC Key in the device.

     *Interactive mode*

     .. code-block:: bash

        $ generate hmackey <session> <key_id> <label> <domains> <capabilities> <algorithm>

     *Command line mode*

     .. code-block:: bash

        $ yubihsm-shell -a generate-hmac-key -i <key_id> -l <label> -d <domains> -c <capabilities> -A <algorithm>

  **Generate Otp Aead Key --** Generates an OTP AEAD Key for Yubico OTP decryption.

     *Interactive mode*

     .. code-block:: bash

        $ generate otpaeadkey <session> <key_id> <label> <domains> <capabilities> <algorithm> <nonce_id>

     *Command line mode*

     .. code-block:: bash

        $ yubihsm-shell -a generate-otp-aead-key -i <key_id> -l <label> -d <domains> -c <capabilities> -A <algorithm> --nonce <nonce_id>

  **Generate Symmetric Key --** Generates a symmetric key.

  	 *Interactive mode*

     .. code-block:: bash

        $ generate symmetric <session> <key_id> <label> <domains> <capabilities> <algorithm>

     *Command line mode*

     .. code-block:: bash

        $ yubihsm-shell -a generate-symmetric-key -i <key_id> -l <label> -d <domains> -c <capabilities> -A <algorithm>


  **Generate Wrap Key --** Generates a Wrap Key that can be used for export, import, wrap data, and unwrap data.

     *Interactive mode*

     .. code-block:: bash

        $ generate wrapkey <session> <key_id> <label> <domains> <capabilities> <delegated_capabilities> <algorithm>

     *Command line mode*

     .. code-block:: bash

        $ yubihsm-shell -a generate-wrap-key -i <key_id> -l <label> -d <domains> -c <capabilities> --delegated <delegated_capabilities> -A <algorithm>

  **Get Device Info --** Gets device version, device serial, supported algorithms and the number of log entries.

     *Interactive mode*

     .. code-block:: bash

        $ get deviceinfo

     *Command line mode*

     .. code-block:: bash

        $ yubihsm-shell -a get-device-info

  **Get Device Public Key	--** Retrieves the device’s public key for the purpose of asymmetric authentication.

     *Interactive mode*

     .. code-block:: bash

         $ get devicepubkey

     *Command line mode*

     .. code-block:: bash

         $ yubihsm-shell -a get-public-key


  **Get Log Entries --** Fetches all current entries from the device Log Store.

     *Interactive mode*

     .. code-block:: bash

        $ audit get <session>

     *Command line mode*

     .. code-block:: bash

        $ yubihsm-shell -a get-logs

  **Get Object Info --** Fetches all metadata about an object.

     *Interactive mode*

     .. code-block:: bash

        $ get objectinfo <session> <object_id> <type>

     *Command line mode*

     .. code-block:: bash

        $ yubihsm-shell -a get-object-info -i <object_id> -t <type>

  **Get Opaque --** Retrieves an Opaque object (like an X.509 certificate) from the device.

     *Interactive mode*

     .. code-block:: bash

        $ get opaque <session> <object-id>

     *Command line mode*

     .. code-block:: bash

        $ yubihsm-shell -a get-opaque -i <object-id>

  **Get Option --** Gets device-global options.

     *Interactive mode*

     .. code-block:: bash

        $ get option <session> <option>

     *Command line mode*

     .. code-block:: bash

        $ yubihsm-shell -a get-option --opt-name <option>

  **Get Pseudo Random --** Extracts a fixed number of pseudo-random bytes from the device, using the internal PRNG.

     *Interactive mode*

     .. code-block:: bash

        $ get random <session> <number_of_bytes> <out=->

     *Command line mode*

     .. code-block:: bash

        $ yubihsm-shell -a get-pseudo-random [--count <number_of_bytes=256> --out <out>]

  **Get Public Key --** Fetches the public key of an Asymmetric  Key.

     *Interactive mode*

     .. code-block:: bash

        $ get pubkey <session> <key_id>

     *Command line mode*

     .. code-block:: bash

        $ yubihsm-shell -a get-public-key -i <key_id>

  **Get Storage Info --** Reports currently free storage.

     *Interactive mode*

     .. code-block:: bash

        $ get storage <session>

  **Get Template  --** Retrieves a Template object from the device.

     *Interactive mode*

     .. code-block:: bash

        $ put template <session> <object_id> <out_data=->

     *Command line mode*

     .. code-block:: bash

        $ yubihsm-shell -a get-template -i <object_id> [--out <out_data>]

  **Import Wrapped --** Imports a wrapped/encrypted object that was previously exported by an YubiHSM 2 device.

     *Interactive mode*

     .. code-block:: bash

        $ put wrapped <session> <wrapkey_id> <data=->

     *Command line mode*

     .. code-block:: bash

        $ yubihsm-shell -a put-wrapped --wrap-id <wrapkey_id> [--in <file>]

  **List Objects  --** Gets a filtered list of objects from the device.

     *Interactive mode*

     .. code-block:: bash

        $ list objects <session> <id=0> <type=any> <domains=0> <capabilities=0> <algorithm=any> <label=>

     *Command line mode*

     .. code-block:: bash

        $ yubihsm-shell -a list-objects -t <type> -A <algorithm> [-i <id> -d <domains> -c <capabilities> -l <label>]

  **Put Asymmetric Key --** Imports an Asymmetric Key into the device.

     *Interactive mode*

     .. code-block:: bash

        $ put asymmetric <session> <object_id> <label> <domains> <capabilities> <key=->

     *Command line mode*

     .. code-block:: bash

        $ yubihsm-shell -a put-asymmetric-key -i <object_id> -l <label> -d <domains> -c <capabilities> [--in <key>]

  **Put Authentication Key --** Stores an Authentication Key in the device.

      *Interactive mode*

      .. code-block:: bash

        $ put authkey <session> <object_id> <label> <domains> <capabilities> <delegated_capabilities> <password=->

      *Command line mode*

      .. code-block:: bash

        $ yubihsm-shell -a put-authentication-key -i <object-id> -l <label> -d <domains> -c <capabilities> --delegated <delegated_capabilities> [--new-password <password>]

  **Put Hmac Key --** Stores an HMAC Key in the device.

       *Interactive mode*

       .. code-block:: bash

         $ put hmackey <session> <object_id> <label> <domains> <capabilities> <algorithm> <key>

  **Put Opaque   --**  Stores Opaque data (like an X.509 certificate) in the device.

      *Interactive mode*

      .. code-block:: bash

         $ put opaque <session> <object_id> <label> <domains> <capabilities> <algorithm> <data=->

      *Command line mode*

      .. code-block:: bash

         $ yubihsm-shell -a put-opaque -i <object-id> -l <label> -d <domains> -c <capabilities> -A <algorithm> [--in <data>]

  **Put Otp Aead Key --** Imports an OTP AEAD Key used for Yubico OTP Decryption.

      *Interactive mode*

      .. code-block:: bash

          $ put otpaeadkey <session> <key_id> <label> <domains> <capabilities> <nonce_id> <key>

  **Put Symmetric Key	--** Imports a symmetric key.

      *Interactive mode*

      .. code-block:: bash

          $ put symmetric <session> <key_id> <label> <domains> <capabilities> <algorithm> <key>

      *Command line mode*

      .. code-block:: bash

          $ yubihsm-shell -a put-symmetric-key -i <key_id> -l <label> -d <domains> -c <capabilities> -A <algorithm> --in <key>


  **Put Template  --** Stores a Template in the device (like the template used when signing SSH certificate).

      *Interactive mode*

      .. code-block:: bash

         $ put template <session> <object_id> <label> <domains> <capabilities> <algorithm> <in_data=->

      *Command line mode*

      .. code-block:: bash

         $ yubihsm-shell -a put-template -i <object_id> -l <label> -d <domains> -c <capabilities> -A <algorithm> [--in <in_data>]

  **Put Wrap Key  --** Imports a key for wrapping into the device.

      *Interactive mode*

      .. code-block:: bash

          $ put wrapkey <session> <object_id> <label> <domains> <capabilities> <delegated_capabilities> <key>

      *Command line mode*

      .. code-block:: bash

         $ yubihsm-shell -a put-wrap-key -i <object_id> -l <label> -d <domains> -c <capabilities> --delegated <delegated_capabilities> --in <key>

  **Randomize Otp Aead --** Creates a new OTP AEAD using random data for key and private ID.

      *Interactive mode*

      .. code-block:: bash

         $ opt aead_random <session> <key_id> <aead>

      *Command line mode*

      .. code-block:: bash

         $ yubihsm-shell -a randomize-otp-aead -i <key_id> --in <aead>

  **Reset Device  --** Resets and reboots the device, deletes all Objects and restores the default Options and Authentication Key.

      *Interactive mode*

      .. code-block:: bash

         $ reset <session>``

      *Command line mode*

      .. code-block:: bash

         $ yubihsm-shell -a reset

  **Rewrap Otp Aead --** Re-encrypts a Yubico OTP AEAD from one OTP AEAD Key to another OTP AEAD Key.

      *Interactive mode*

      .. code-block:: bash

         $ otp rewrap <session> <key_id_from> <key_id_to> <aead_in> <aead_out>

  **Session Message --** Sends a wrapped command for a previously established session. The command is encrypted and authenticated.

  **Set Log Index --** Informs the device what the last extracted log entry is so logs can be reused.

      *Interactive mode*

      .. code-block:: bash

         $ audit set <session> <index>

      *Command line mode*

      .. code-block:: bash

         $ yubihsm-shell -a set-log-index --log-index <index>

  **Set Option  --** Sets device-global options that affect general behavior.

       *Interactive mode*

       .. code-block:: bash

          $ put option <session> <option> <value>

       *Command line mode*

       .. code-block:: bash

          $ yubihsm-shell -a put-option --opt-name <option> --opt-value <value>

  **Sign Attestation Certificate --** Gets attestation of an Asymmetric Key in the form of an X.509 certificate.

       *Interactive mode*

       .. code-block:: bash

          $ attest asymmetric <session> <key_id> <attest_id=0 <file=->

       *Command line mode*

       .. code-block:: bash

          $ yubihsm-shell -a sign-attestation- certificate -i <key_id> --attestation-id <attest_id> [--out <file>]

  **Sign Ecdsa  --** Computes a digital signature using ECDSA on the provided data.

       *Interactive mode*

       .. code-block:: bash

          $ sign ecdsa <session> <key_id> <signing_algorithm> <in_data=-> <out-data=->

       *Command line mode*

       .. code-block:: bash

          $ yubihsm-shell -a sign-ecdsa -i <key_id> -A <signing_algorithm> [--in <in_data> --out <out_data>]

  **Sign Eddsa  --** Computes a digital signature using EdDSA on the provided data.

       *Interactive mode*

       .. code-block:: bash

          $ sign eddsa <session> <key_id> <algorithm> <data=-> <out=->

       *Command line mode*

       .. code-block:: bash

          $ yubihsm-shell -a sign-eddsa -i <key_id> -A <algorithm> [--in <data> --out <out>]

  **Sign Hmac  --** Performs an HMAC operation in the device and returns the result.

       *Interactive mode*

       .. code-block:: bash

          $ hmac <session> <object_id> <data_to_sign=- in hex> <out=->

       *Command line mode*

       .. code-block:: bash

          $ yubihsm-shell -a sign-hmac -i <object_id> [--in <data_to_sign_in_hex> --in <out_data>]

  **Sign Pkcs1  --** Computes a digital signature using RSA-PKCS1v1.5 on the provided data.

       *Interactive mode*

       .. code-block:: bash

          $ sign pkcs1v1_5 <session> <object_id> <algorithm> <data=-> <out=->

       *Command line mode*

       .. code-block:: bash

          $ yubihsm-shell -a sign-pkcs1v15 -i <object_id> -A <algorithm> [--in <data> --out <out>]

  **Sign Pss  --** Computes a digital signature using RSA-PSS on the provided data.

        *Interactive mode*

        .. code-block:: bash

           $ sign pss <session> <key_id> <signing_algorithm> <in_data=-> <out_file=->

        *Command line mode*

        .. code-block:: bash

           $ yubihsm-shell -a sign-pss -i <key_id> -A <signing_algorith> [--in <in_data> --out <out_file>]

  **Sign Ssh Certificate --** Produces an SSH Certificate signature (only works with RSA keys).

         *Interactive mode*

         .. code-block:: bash

            $ certify <session> <key_id> <template_id> <algorithm> <in_data_in_binary_format=-> <out_data=->

         *Command line mode*

         .. code-block:: bash

            $ yubihsm-shell -a sign-ssh-certificate -i <key_id> --template-id <template_id> -A <algorithm> [--in <in_data_in_binary_format> --out <out_data>]

  **Unwrap Data  --** Decrypts (unwraps) data using a Wrap Key.

         *Interactive mode*

         .. code-block:: bash

            $ decrypt aesccm <session> <key_id> <data=->

  **Verify Hmac  --** Verifies a generated HMAC

  **Wrap Data  --** Encrypts (wraps) data using a Wrap Key.

         *Interactive mode*

         .. code-block:: bash

            $ encrypt aesccm <session> <key_id> <data=->


YubiHSM 2 Shell Algorithm Names
---------------------------------

Following table describes algorithm names to be used with YubiHSM Shell for the algorithms supported by YubiHSM 2.


.. table::

  +-----------------------------+------------------------------+----------------+
  | Name                        | yubihsm-shell name           | Comment        |
  +=============================+==============================+================+
  | AES 128                     | aes128                       |                |
  +-----------------------------+------------------------------+----------------+
  | AES 192                     | aes192                       |                |
  +-----------------------------+------------------------------+----------------+
  | AES 256                     | aes256                       |                |
  +-----------------------------+------------------------------+----------------+
  | AES CBC                     | aes-cbc                      |                |
  +-----------------------------+------------------------------+----------------+
  | AES ECB                     | aes-ecb                      |                |
  +-----------------------------+------------------------------+----------------+
  | AES128 CCM WRAP             | aes128-ccm-wrap              |                |
  +-----------------------------+------------------------------+----------------+
  | AES192 CCM WRAP             | aes192-ccm-wrap              |                |
  +-----------------------------+------------------------------+----------------+
  | AES256 CCM WRAP             | aes256-ccm-wrap              |                |
  +-----------------------------+------------------------------+----------------+
  | EC BP256                    | ecbp256                      | brainpool256r1 |
  +-----------------------------+------------------------------+----------------+
  | EC BP384                    | ecbp384                      | brainpool384r1 |
  +-----------------------------+------------------------------+----------------+
  | EC BP512                    | ecbp512                      | brainpool512r1 |
  +-----------------------------+------------------------------+----------------+
  | EC ECDH                     | ecdh                         |                |
  +-----------------------------+------------------------------+----------------+
  | EC K256                     | eck256                       | secp256k1      |
  +-----------------------------+------------------------------+----------------+
  | EC P224                     | ecp224                       | secp224r1      |
  +-----------------------------+------------------------------+----------------+
  | EC P256                     | ecp256                       | secp256r1      |
  +-----------------------------+------------------------------+----------------+
  | EC P384                     | ecp384                       | secp384r1      |
  +-----------------------------+------------------------------+----------------+
  | EC P521                     | ecp521                       | secp521r1      |
  +-----------------------------+------------------------------+----------------+
  | ECDSA SHA1                  | ecdsa-sha1                   |                |
  +-----------------------------+------------------------------+----------------+
  | ECDSA SHA256                | ecdsa-sha256                 |                |
  +-----------------------------+------------------------------+----------------+
  | ECDSA SHA384                | ecdsa-sha384                 |                |
  +-----------------------------+------------------------------+----------------+
  | ECDSA SHA512                | ecdsa-sha512                 |                |
  +-----------------------------+------------------------------+----------------+
  | ED25519                     | ed25519                      |                |
  +-----------------------------+------------------------------+----------------+
  | HMAC SHA1                   | hmac-sha1                    |                |
  +-----------------------------+------------------------------+----------------+
  | HMAC SHA256	                | hmac-sha256                  |                |
  +-----------------------------+------------------------------+----------------+
  | HMAC SHA384	                | hmac-sha384                  |                |
  +-----------------------------+------------------------------+----------------+
  | HMAC SHA512	                | hmac-sha512                  |                |
  +-----------------------------+------------------------------+----------------+
  | MGF1 SHA1                   | mgf1-sha1                    |                |
  +-----------------------------+------------------------------+----------------+
  | MGF1 SHA256	                | mgf1-sha256                  |                |
  +-----------------------------+------------------------------+----------------+
  | MGF1 SHA384	                | mgf1-sha384                  |                |
  +-----------------------------+------------------------------+----------------+
  | MGF1 SHA512	                | mgf1-sha512                  |                |
  +-----------------------------+------------------------------+----------------+
  | Opaque Data	                | opaque-data                  |                |
  +-----------------------------+------------------------------+----------------+
  | Opaque X509 Certificate     | opaque-x509-certificate      |                |
  +-----------------------------+------------------------------+----------------+
  | RSA 2048                    | rsa2048                      |                |
  +-----------------------------+------------------------------+----------------+
  | RSA 3072                    | rsa3072                      |                |
  +-----------------------------+------------------------------+----------------+
  | RSA 4096                    | rsa4096                      |                |
  +-----------------------------+------------------------------+----------------+
  | RSA OAEP SHA1               | rsa-oaep-sha1                |                |
  +-----------------------------+------------------------------+----------------+
  | RSA OAEP SHA256             | rsa-oaep-sha256              |                |
  +-----------------------------+------------------------------+----------------+
  | RSA OAEP SHA384             | rsa-oaep-sha384              |                |
  +-----------------------------+------------------------------+----------------+
  | RSA OAEP SHA512             | rsa-oaep-sha512              |                |
  +-----------------------------+------------------------------+----------------+
  | RSA PKCS1 SHA1              | rsa-pkcs1-sha1               |                |
  +-----------------------------+------------------------------+----------------+
  | RSA PKCS1 SHA256            | rsa-pkcs1-sha256             |                |
  +-----------------------------+------------------------------+----------------+
  | RSA PKCS1 SHA384            | rsa-pkcs1-sha384             |                |
  +-----------------------------+------------------------------+----------------+
  | RSA PKCS1 SHA512            | rsa-pkcs1-sha512             |                |
  +-----------------------------+------------------------------+----------------+
  | RSA PSS SHA1                | rsa-pss-sha1                 |                |
  +-----------------------------+------------------------------+----------------+
  | RSA PSS SHA256              | rsa-pss-sha256               |                |
  +-----------------------------+------------------------------+----------------+
  | RSA PSS SHA384              | rsa-pss-sha384               |                |
  +-----------------------------+------------------------------+----------------+
  | RSA PSS SHA512              | rsa-pss-sha512               |                |
  +-----------------------------+------------------------------+----------------+
  | SSH Template                | template-ssh                 |                |
  +-----------------------------+------------------------------+----------------+
  | Yubico AES Authentication   | aes128-yubico-authentication |                |
  +-----------------------------+------------------------------+----------------+
  || Yubico Asymmetric          | ecp256-yubico-authentication |                |
  || Authentication             |                              |                |
  +-----------------------------+------------------------------+----------------+
  | Yubico OTP AES128           | aes128-yubico-otp            |                |
  +-----------------------------+------------------------------+----------------+
  | Yubico OTP AES192           | aes192-yubico-otp            |                |
  +-----------------------------+------------------------------+----------------+
  | Yubico OTP AES256           | aes256-yubico-otp            |                |
  +-----------------------------+------------------------------+----------------+



.. _hsm2-connector-label:

YubiHSM 2 Connector
====================

The `yubihsm-connector <https://developers.yubico.com/yubihsm-connector/>`_ performs the communication between the YubiHSM 2 and the applications that use it.

The Connector must have permissions to access the USB device, and different operating systems behave differently in this regard. The easiest way to get started is to run the Connector with Administrator privileges (e.g. with ``sudo``), but the safest way to run the Connector is to use your operating system’s configuration to give it only the privileges necessary to access the YubiHSM 2 USB device.

The Connector is not a trusted component. Sessions are established cryptographically between the application and the YubiHSM 2 using a symmetric mutual authentication scheme that is both encrypted and authenticated.

The Connector is not required to run on the same host as the applications which access it. In that case, configure the Connector to listen on a different address rather than the default ``localhost:12345``. Make sure that the client has access. The port number does not need to change, only the address. Also, make sure that OS firewalls are configured properly to allow access to the host machine on the specified port.

To get information regarding the Connector issue a GET request on the ``/connector/status`` URI.


HTTPS Connections
-------------------

As mentioned earlier, the Connector is not meant to be a trusted component. For this reason it defaults to HTTP connections. It is possible to use HTTPS, however this requires providing a key and a certificate to the Connector.

Another option is to use a reverse proxy such as nginx before the Connector and have that handle TLS.

Sample Configuration
---------------------

Sample configuration for the Connector: ``yubihsm-connector-config.yaml``

.. code-block:: bash

   # Certificate (X.509)
   cert: ""

   # Certificate key
   key: ""

   # Listening address. Defaults to "localhost:12345".
   listen: localhost:12345

   # Device serial in case of multiple devices
   serial: ""

   # Log to syslog/eventlog. Defaults to "false".
   syslog: false

   # Use to enable host header filtering. Default to "false".
   # Use this if there is an absolute need to use a web browser on the
   # host where the YubiHSM 2 is installed to connect to untrusted web
   # sites on the Internet.
   enable-host-whitelist: false

   # Default list for the host header filter
   host-whitelist: localhost,localhost.,127.0.0.1,[::1]


Sample ``udev`` rule to be placed into ``/etc/udev/rules.d/``

.. code-block:: bash

   #This udev file should be used with udev 188 and newer
   ACTION!="add|change", GOTO="yubihsm2_connector_end"

   # Yubico YubiHSM 2
   # The OWNER attribute here has to match the uid of the process
   # running the Connector
   SUBSYSTEM=="usb", ATTRS{idVendor}=="1050", ATTRS{idProduct}=="0030",
     OWNER="yubihsm-connector"

   LABEL="yubihsm2_connector_end"


.. _hsm2-wrap-label:

YubiHSM Wrap
=============

`Yubihsm Wrap <https://developers.yubico.com/yubihsm-shell/yubihsm-wrap.html>`_ is a tool that allows the creation of importable objects offline. This is useful when bootstrapping secrets, for example on an air-gapped computer.

The tool requires an unencrypted Wrap Key in binary format and uses that to wrap objects with given Type, :ref:`hsm2-concepts-objects-label`, :ref:`hsm2-concepts-algorithms-label`, :ref:`hsm2-concepts-objectid-label`, :ref:`hsm2-concepts-capability-label` and, where applicable, Delegated Capabilities.

For the resulting Object to be successfully imported on a YubiHSM 2, the Wrap Key used by ``yubihsm-wrap`` must already be present on the device.

Currently not all Object Types are supported. Refer to `Known Issues and Limitations <https://developers.yubico.com/YubiHSM2/Releases/Known_issues.html>`_ for more information.

.. _hsm2-libyubishm-label:

Libyubihsm
============

`Libyubihsm <https://developers.yubico.com/yubihsm-shell/libyubihsm.html>`_ is the C library used to communicate natively with a YubiHSM 2. It implements and exposes convenience functions for all the commands supported by the device. It also allows the sending of unformatted “raw” messages over an established session or in plain text.

The library is used by:

 * 	**yubihsm-shell**, see `YubiHSM Shell Reference <https://docs.yubico.com/software/yubihsm-2/component-reference/hsm2-ref-shell.html#hsm2-ref-shell-label>`_

 * 	**PKCS#11 module**, see `PKCS#11 with YubiHSM 2 Reference <https://docs.yubico.com/software/yubihsm-2/component-reference/hsm2-ref-pkcs11.html#hsm2-ref-pkcs11-label>`_

 * 	**KSP**, see `Key Storage Provider Reference <https://docs.yubico.com/software/yubihsm-2/component-reference/hsm2-ref-ksp.html#hsm2-ref-ksp-label>`_

Documentation of the library API can be found as comments within the header file (``yubihsm.h``) in the `SDK <https://developers.yubico.com/YubiHSM2/Releases>`_, or as a pre-built `Doxygen bundle <https://developers.yubico.com/YubiHSM2/Releases>`_.

Libyubihsm includes a connector component to talk to a YubiHSM device. This connector is different from the yubihsm-connector discussed earlier. This component can be one of the following two types.

HTTP Connector
---------------

This kind of Connector talks to yubihsm-connector over http(s), allowing remote access to a YubiHSM2, see `Connector Reference <https://docs.yubico.com/software/yubihsm-2/component-reference/hsm2-ref-connector.html#hsm2-ref-connector-label>`_

In order to select this type of backend the connector URL should use the ``http`` or ``https`` scheme; for example, to use a local HTTP Connector use ``http://127.0.0.1:12345``.

USB Connector
--------------

This kind of Connector is a direct-access USB backend that talks directly with a YubiHSM device. The USB Connector is built into ``libyubihsm``. This renders it unnecessary to run an additional component (i.e., the external Connector) at the cost of requiring exclusive access to a YubiHSM device.

To select this type of backend the connector URL should use the ``yhusb`` scheme. For example, to use a local device with serial number 123456 use ``yhusb://serial=123456``.

.. _hsm2-python-library-label:

Python Library
================

The `Python library <https://developers.yubico.com/python-yubihsm/>`_ allows you to interface with a YubiHSM 2 through both the Connector service and direct USB connection using the Python programming language. It supports both Python 2 and Python 3.

The recommended way to install the library is by using ``pip`` inside a ``virtualenv``. To create and activate a ``virtualenv``, run:

.. code-block:: bash

   $ virtualenv yubihsm
   Running virtualenv with interpreter /usr/bin/python3
   New python executable in /home/user/yubihsm/bin/python3
   Also creating executable in /home/user/yubihsm/bin/python
   Installing setuptools, pkg_resources, pip, wheel...done.

   $ source yubihsm/bin/activate
   (yubihsm) $ pip install yubihsm[http,usb]
   Collecting yubihsm-2.0.0
   ...
   Successfully installed asn1crypto-0.22.0 cffi-1.10.0 cryptography-1.8.1
      enum34-1.1.6 idna-2.5 ipaddress-1.0.18 pycparser-2.17 pyusb-1.0.2
      requests-2.13.0 yubihsm-2.0.0
   (yubihsm) $



.. Note::
   The ``cryptography`` dependency uses C extensions, and therefore has some build dependencies. For detailed instructions, see: https://cryptography.io/en/latest/installation/

   .. code-block:: bash

      from yubihsm import YubiHsm
      from yubihsm.objects import AsymmetricKey
      from yubihsm.defs import ALGORITHM, CAPABILITY

      # Connect to the Connector and establish a session using the default
      # auth key:
      hsm = YubiHsm.connect("http://localhost:12345/connector/api")
      session = hsm.create_session_derived(1, "password")

      # Create a new EC key for signing:
      key = AsymmetricKey.generate(session, 0, "EC Key", 1, CAPABILITY.SIGN_ECDSA, ALGORITHM.EC_P256)

      # Sign a message
      data = b'Hello world!'
      signature = key.sign_ecdsa(data)

      # Delete the key from the YubiHSM 2
      key.delete()

      # Close session and connection:
      session.close()
      sm.close()

.. _hsm2-ksp-windows-label:

Key Storage Provider (KSP) – Windows Only
==========================================

The Key Storage Provider (KSP) for Windows Cryptography API: Next Generation (CNG) has been thoroughly tested with Active Directory Certificate Services (AD CS) plus 2048-bit, 3072-bit, and 4096-bit keys. It also works with other types of keys, but those have not been tested to the same extent.

The following installs the KSP and the Connector Service, using them for ADCS with the default Authentication Key (``1``) and password (``password``).

When you run the ``Install-AdcsCertificationAuthority`` command, you should see the YubiHSM 2 light flash rapidly, because AD CS uses the KSP to generate a 2048-bit key in hardware. For AD CS to work properly, ``Restart-Computer`` may be needed.

.. code-block:: bash

   PS1> msiexec /i "yubihsm-connector-windows-amd64.msi" /passive ACCEPT=yes
   PS1> msiexec /i "yubihsm-cngprovider-windows-amd64.msi" /passive  ACCEPT=yes
   PS1> Install-WindowsFeature AD-Certificate -Verbose
   PS1> Install-AdcsCertificationAuthority -CAType EnterpriseRootCa    \
       -CryptoProviderName "RSA#YubiHSM Key Storage Provider"          \
       -KeyLength 2048 -HashAlgorithmName SHA256 -ValidityPeriod Years \
       -ValidityPeriodUnits 5
   PS1> Install-AdcsOnlineResponder


If you are using a different Authentication Key, password, or Connector for the KSP, you can specify them as follows (defaults are shown):

.. code-block:: bash

   PS1> Set-ItemProperty -path HKLM:\SOFTWARE\Yubico\YubiHSM \
       -name ConnectorURL -Type String -Value http://127.0.0.1:12345
   PS1> Set-ItemProperty -path HKLM:\SOFTWARE\Yubico\YubiHSM \
       -name AuthKeysetPassword -Type String -Value password
   PS1> Set-ItemProperty -path HKLM:\SOFTWARE\Yubico\YubiHSM \
       -name AuthKeysetID -Type DWord -Value 1


.. Warning:: Design considerations for Key Storage Providers in Windows prevent the direct USB functionality of libyubihsm (Connector URL ``yhusb://``), therefore it is not supported in this version of the YubiHSM KSP.


The default configuration for the connector is: ``ProgramData\YubiHSM\yubihsm-connector.yaml`` - Administrator rights are required to access the file.


Additional Documentation for YubiHSM Key Storage Provider
------------------------------------------------------------

 * For instructions on how to move a software-based key into the YubiHSM 2 for use with the KSP, see `Move Software Keys to Key Storage Provider <https://docs.yubico.com/software/yubihsm-2/component-reference/hsm2-ref-ksp-move-sw-keys.html>`_.

 *	For an example of how to create an HSM-backed code signing certificate for Windows through the KSP, see :ref:`hsm2-ksp-windows-code-signing-cert-ksp-label`.

 * 	For more information about status codes, see `YubiHSM 2 status codes <https://docs.yubico.com/software/yubihsm-2/component-reference/hsm2-ref-ksp-status-codes.html>`_ in Windows.

 * 	For details on how to configure the 32-bit and 64-bit KSP DLLs, please see :ref:`hsm2-ksp-windows-server-guide-label`.

.. _hsm2-auth-label:

YubiHSM Auth
==============

**YubiHSM Auth** is a new YubiKey module that serves as a key storage for authenticating against a YubiHSM 2 with a YubiKey instead of just using a session password alone. To leverage this functionality, use the latest release of `YubiHSM 2 SDK <https://developers.yubico.com/YubiHSM2/Releases/>`_.

YubiHSM Auth is a YubiKey CCID application that stores the long-lived credentials used to establish secure sessions to a YubiHSM 2. The secure session protocol is based on `Secure Channel Protocol 3 (SCP03) <hhttps://docs.yubico.com/hardware/yubikey/yk-tech-manual/scp03-specifics.html>`_. YubiHSM Auth is supported by YubiKey v5.4.0 and higher.

YubiHSM Auth uses hardware to protect the long-lived credentials for accessing a YubiHSM 2. This increases the security of the authentication credentials, as compared to the authentication solution for the YubiHSM 2 based on software credentials derived from the Password-Based Key Derivation Function 2 (PBKDF2) algorithm with a password as input.

.. Note:: SCP03 is always used, with yubihsm-auth or not. This means that authentication is always based on a pair of 128 bit AES keys. These keys can be derived from a password on the client side, using authentication in the Yubico command line tools.

Credentials and PIN Codes
---------------------------

Each YubiHSM Auth credential consists of two AES-128 keys which are used to derive the three session-specific AES-128 keys. The YubiHSM Auth application can store up to 32 YubiHSM Auth credentials in the YubiKey.

Each YubiHSM Auth credential is protected by a 16-byte user access code provided to the YubiKey for each YubiHSM Auth operation. The access code is used to access the YubiHSM Auth Credential to derive the session-specific AES-128 keys.

Storing or deleting YubiHSM Auth credentials requires a separate 16-byte admin access code.

Each access code has a limit of eight retries and optionally, verification of user presence (touch).

YubiHSM 2 Secure Channel
--------------------------

YubiKey YubiHSM Auth application can be used to establish an encrypted and authenticated session to a YubiHSM 2. Although the YubiHSM 2 secure channel is based on the protocol Global Platform Secure Channel Protocol ‘03’ (SCP03), there are two important differences:

 *	The YubiHSM 2 secure channel protocol does not use APDUs, so the commands and possible options are not those of the complete SCP03 specification.

 *	SCP03 uses key sets with three long-lived AES keys. Two of these long-lived keys are used for authentication and the third is used to encrypt new long-lived keys when they’re transferred to the device. Since YubiHSM handles authentication keys like any other keys, the third SCP03 long-lived key is not required therefore YubiHSM 2 secure channel uses key sets with two long-lived AES keys  which are required for authentication.

The YubiHSM 2 authentication protocol uses a set of static credentials called a long-lived key set. This consists of two AES-128 keys:

 * 	**ENC**: Used for deriving keys for command and response encryption, as specified in SCP03.

 *	**MAC**: Used for deriving keys for command and response authentication, as specified in SCP03.

The identical long-lived keyset is protected in the YubiHSM 2 and in the YubiKey YubiHSM Auth application.

Those long-lived key sets are used by the YubiHSM Auth application to derive a set of three session-specific AES-128 keys using the challenge-response protocol as defined in SCP03:

 * 	**Session Secure Channel Encryption Key (S-ENC)**: Used for data confidentiality.

 * 	**Secure Channel Message Authentication Code Key for Command (S-MAC)**: Used for data and protocol integrity.

 *	**Secure Channel Message Authentication Code Key for Response (S-RMAC)**: Used for data and protocol integrity.

The YubiHSM Auth session-specific keys are output from the YubiKey to the calling library, which uses the session keys to encrypt and authenticate commands and responses during a single session. After the session is over the session keys are discarded. Session keys are only used for a single session and are not sensitive after the session is over.

Architecture Overview
-----------------------

The figure below shows how the YubiHSM Auth application fits in to the YubiHSM 2 architecture.

.. image:: /graphics/yb-architecture-w-ybauth.png
    :scale: 100%
    :align: left

**Figure: Architecture Overview**

The identical long-lived credentials (key sets) are protected in both the YubiKey YubiHSM Auth application and in the YubiHSM 2. The YubiHSM-Shell software tool can be used for generating the key sets in the YubiHSM 2, and the YubiHSM-Auth software tool can be used for importing the same key sets to the YubiKey YubiHSM Auth application.

At the client, the YubiHSM authentication protocol is implemented in the ``libykhsmauth`` library, which derives the three session AES-keys by calling the YubiKey YubiHSM Auth CCID application. The session objects that are created can be used by the ``libyubihsm`` in the communication with YubiHSM.

The YubiHSM session keys are therefore generated on the basis of the long-lived credentials that are protected in the YubiHSM 2 and YubiKey YubiHSM Auth in conjunction with the SCP03 derivation scheme.


YubiHSM Auth Flowchart
------------------------

The flowchart below illustrates the authentication protocol communication with YubiHSM using the static keys on YubiHSM Auth. It is assumed that the YubiHSM and YubiHSM Auth application share the same static keyset. The steps are explained below.

.. image:: /graphics/yb-auth-flowchart.png
    :scale: 100 %
    :align: center

**Figure: YubiHSM Auth Flowchart**


The following is a description of the steps in the flowchart.

 1.	The user launches YubiHSM-Shell and enters the commands ``connect`` and ``session open``, with the flag ``ykopen`` that indicates that the YubiKey with YubiHSM Auth shall be used.

 2.	The YubiHSM-Shell invokes the ``libyubihsm`` library, with a request to open a session to the YubiHSM 2.

 3.	The ``libyubihsm`` library generates a host challenge and opens a session to the YubiHSM 2 device.

 4.	The YubiHSM 2 device generates an HSM challenge and generates the session keys based on the HSM challenge, the host challenge, and the static key set in the YubiHSM 2 device. The YubiHSM 2 returns the HSM challenge in an HSM response to the ``libyubihsm`` library.

 5.	The ``libyubihsm`` library propagates the host challenge and HSM challenge to the YubiHSM Shell.

 6.	The user enters the Credential password for unlocking the static keyset in the YubiHSM Auth application in the YubiKey. The YubiHSM Shell invokes the ``libykhsmauth`` library, with a request to generate session keys.

 7.	The ``libykhsmauth`` library invokes the YubiHSM Auth application in the YubiKey with the Credential password, the HSM challenge and host challenge are used as input parameters.

 8.	The Credential password unlocks the static keyset in the YubiHSM Auth application, and the YubiHSM Auth application generates the session keys based on the static keys, HSM challenge, and host challenge.

 9.	The ``libykhsmauth`` library returns the session keys to YubiHSM Shell.

 10.	The YubiHSM Shell acknowledges the protocol handshake to ``libyubihsm``.

 11.	The ``libyubihsm`` sends the host response to the YubiHSM 2 device. The session keys can now be used for secure channel communication between ``YubiHSM-Shell/libyubihsm`` in the host and the YubiHSM device.


YubiHSM-Auth Software Tool
---------------------------

The YubiHSM-Auth software tool is part of the `YubiHSM Shell <https://docs.yubico.com/software/yubihsm-2/component-reference/hsm2-ref-shell.html>`_, which is installed with the `YubiHSM SDK <https://developers.yubico.com/YubiHSM2/Releases/>`_. YubiHSM-Auth tool can be used for:

 * Storing the YubiHSM Auth credentials on a YubiKey

 * Deleting the YubiHSM Auth credentials on a YubiKey

 * Listing the YubiHSM Auth credentials on a YubiKey

 * Changing the YubiHSM Auth management key on a YubiKey

 * Checking the number of retries of the YubiHSM Auth credential password

 * Checking the version of the YubiHSM Auth application

 * Calculating session keys, mainly for debugging and test purposes

 * Resetting the YubiHSM Auth application on a YubiKey

First, the YubiHSM 2 device needs to be configured with an authentication key. The default authentication key password on ``KeyID=1`` is set to ``password``, and this should be changed or replaced with other authentication keys. For the examples in this section, however, it is assumed that the default authentication key is still present on the YubiHSM 2.

In order to generate and store the equivalent YubiHSM Auth credentials on the YubiKey, the ``yubihsm-auth`` command line tool can be used. To invoke YubiHSM-Auth simply run ``yubihsm-auth`` with the required commands and parameters.

To get a list of available commands, parameters and their syntax, run:

``yubihsm-auth --help``

An example of how to use ``yubihsm-auth`` for storing YubiHSM Auth credentials on a YubiKey is shown below:

.. code-block:: bash

   $ yubihsm-auth -a put --label="default key" --derivation-password="password" --credpwd="MyPassword" --touch=on --mgmkey="00000000000000000000000000000000" --verbose=5
   Credential successfully stored


where--

 * 	``-a put`` is the action to insert a YubiHSM Auth credential on the YubiKey

 *	``--label`` is the label of the YubiHSM Auth credential on the YubiKey

 * 	``--derivation-password`` is used as input to the PBKDF2 algorithm, which is used for generating the two AES-128 keys that constitute the YubiHSM Auth credentials to be stored on the YubiKey

 *	``--credpwd`` is the password protecting the YubiHSM Auth credentials on the YubiKey

 *	``--touch`` is set to ‘on’, which requires the user to touch the YubiKey when accessing the YubiHSM Auth credential

 *	``--mgmkey`` is the management key that is needed for writing the YubiHSM Auth credentials on the YubiKey

 *	``--verbose`` is used to print more information as output

.. Note::
   We recommend using an offline air-gapped computer when storing the YubiHSM Auth credentials on the YubiKey.
   Now the YubiKey YubiHSM Auth application can be used with `YubiHSM Shell <https://docs.yubico.com/software/yubihsm-2/component-reference/hsm2-ref-shell.html>`_ for authentication to the YubiHSM 2.


Using YubiHSM-Auth with YubiHSM Shell
--------------------------------------

It is now possible to authenticate to the YubiHSM 2 device with static credentials that are protected in the YubiKey application called YubiHSM Auth. For more information on this YubiKey feature and how to configure it, see Using YubiHSM Auth.

The YubiHSM Shell tool supports authentication with YubiHSM Auth credentials in both interactive mode and command line mode.

In order to use yubihsm-shell with the YubiHSM Auth-enabled YubiKey in interactive mode, open a session by executing the following yubihsm-shell command:

``yubihsm> session ykopen <authkey> <label> <password>``

Where, in the context of using YubiHSM-Shell with the YubiHSM Auth application, the following parameters are used:

 * ``authkey`` is the identifier of the authentication key in the YubiHSM 2

 * ``label`` is the label of the YubiHSM-Auth credetnials stored in the YubiKey

 * ``password`` is the password that protects the YubiHSM-Auth credentials stored in the YubiKey.

Below is an example of an interactive command with YubiHSM Shell:

.. code-block:: bash

   yubihsm> session ykopen 1 "default key" "MyPassword"
   trying to connect to reader 'Yubico YubiKey OTP+FIDO+CCID 0'
   Created session 0


To use yubihsm-shell with YubiHSM Auth in command line mode, add the parameter ``--ykhsmauth-label`` that implicitly invokes the YubiHSM Auth application at the YubiKey. Below is an example of how to use YubiHSM Shell in command line mode:


.. code-block:: bash

     $ yubihsm-shell --ykhsmauth-label "default key" -p "MyPassword"
        -a generate-asymmetric -A rsa2048 -i 11 -c sign-pss -l Signature_Key``


If the YubiKey is configured to require touch when accessing the YubiHSM-Auth credentials, the user needs to touch the YubiKey sensor in addition to entering the credential password.

Once the user is authenticated with YubiHSM Auth, all YubiHSM-Shell commands can be used.