.. hsm2-sdk-tools-libraries.rst
.. _hsm2-sdk-tools-libraries-label:
===================================
YubiHSM 2 SDK Tools And Libraries
===================================
.. _hsm2-download-label:
YubiHSM 2 SDK Downloads
========================
YubiHSM 2 SDK can be downloaded from https://developers.yubico.com/YubiHSM2/Releases/ and contains the following tools and libraries to interface with YubiHSM 2.
.. table::
+-------------------------------+---------------------------------------------+
| Resource | Description |
+===============================+=============================================+
| bin/libcrypto-3.dll | Pre-built OpenSSL (Windows and MacOS only) |
| or lib/libcrypto-3.dylib | |
+-------------------------------+---------------------------------------------+
| bin/yubihsm-setup | Deployment tool for YubiHSM 2 |
+-------------------------------+---------------------------------------------+
| bin/yubihsm-wrap || A tool to create wrapped importable |
| || objects offline |
+-------------------------------+---------------------------------------------+
| bin/yubihsm-connector || The Connector, a tool for providing a |
| || common interface to the device |
+-------------------------------+---------------------------------------------+
| bin/yubihsm-shell || The shell, a REPL-style tool for |
| || interacting with YubiHSM 2 (and the |
| || Connector) See Note (1) |
+-------------------------------+---------------------------------------------+
| include/pkcs11/pkcs11.h || Common and standard PKCS#11 functions and |
| || constants definitions |
+-------------------------------+---------------------------------------------+
| include/pkcs11/pkcs11y.h || Yubico-specific PKCS#11 functions and |
| || constants definitions |
+-------------------------------+---------------------------------------------+
| include/yubihsm.h | Library functions and constants definitions |
+-------------------------------+---------------------------------------------+
|| lib/libyubihsm.{dylib,so} | Library binary to interact with YubiHSM 2 |
|| or bin/libyubihsm.dll | |
+-------------------------------+---------------------------------------------+
|| lib/yubihsm_pkcs11.{dylib,so}| PKCS#11 module to interact with YubiHSM 2 |
|| or bin/yubihsm_pkcs11.dll | |
+-------------------------------+---------------------------------------------+
| python-noarch (**1**) | Python implementation of the library |
+-------------------------------+---------------------------------------------+
|| yubihsm-cngprovider-windows- || Installer for CNG/KSP for Windows ADCS |
|| amd64.msi || (Windows only) |
+-------------------------------+---------------------------------------------+
|| yubihsm-connector-windows- | Installer for the Connector (Windows only) |
|| amd64.msi | |
+-------------------------------+---------------------------------------------+
**(1)** python-noarch is a separate download. See `python-yubihsm `_.
Details on these tools and libraries can be found in the later sections of this document.
YubiHSM 2 Communication
=========================
Users and applications communicate with the YubiHSM 2 through either HTTP and USB using the `yubihsm-connector `_. See :ref:`hsm2-connector-label`.
HTTP Access to YubiHSM
-----------------------
This kind of connection talks to yubihsm-connector over http(s), allowing remote access to a YubiHSM2, see `Connector Reference `_.
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``.
.. Note:: HTTP is default configuration.
USB Access to YubiHSM
----------------------
This kind of connection 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-setup-tool-label:
YubiHSM 2 Setup Tool
=====================
The SDK ships with a tool called `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 also generates an asymmetric key pair 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 key pair and one corresponding X509 certificate.
.. Note::
Using the ``--no-new-authkey`` flag prevents generation of a new Wrap Key and a new Authentication Key.
How It Works
-------------
For the JAVA implementation, a key pair 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 2 Shell
================
The `yubihsm-shell `_ 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``.
See :ref:`hsm2-cmd-reference-label` for yubihsm-shell commands interactive and command line mode examples.
.. _hsm2-connector-label:
YubiHSM 2 Connector
====================
The `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.
Communicating with the YubiHSM Connector
-----------------------------------------
As mentioned earlier, the YubiHSM 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-auth-label:
YubiHSM 2 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 `_.
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) `_. 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 `_, which is installed with the `YubiHSM SDK `_. 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 `_ 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