.. hsm2-tools-manager.rst
.. _hsm2-tools-manager-label:
===================
YubiHSM 2 Manager
===================
YubiHSM Manager is an interactive command line tool for managing and operating the YubiHSM 2 device. It provides a
guided, menu-driven interface for common key management and device operations, making it easier for administrators to
perform tasks such as generating keys, creating authentication credentials, backing up and restoring device contents,
and setting up provider integrations — without needing to construct raw commands.
YubiHSM Manager supersedes the previous ``yubihsm-setup`` tool. It retains all of the setup-oriented workflows that
``yubihsm-setup`` provided while expanding the functionality to include general-purpose key management, cryptographic
operations (signing, decryption, ECDH derivation), device backup and restore, and session recording for repeatable
provisioning. However, ``yubihsm-manager`` is still more limited than ``yubihsm-shell`` as it focuses on the most
commonly used operations rather than exposing the complete YubiHSM 2 API surface.
.. _hsm2-mgr-run-label:
Running YubiHSM Manager
==========================
YubiHSM Manager runs on Windows, macOS, and Linux.
#. Installer packages for YubiHSM Manager are available for download from two places:
* From `YubiHSM-Manager Releases `_ as a standalone tool
* From `YubiHSM2 Releases `_ as part of the YubiHSM SDK
Download the installer package for your operating system. Double click on the installer package and follow the installation wizard.
#. YubiHSM Manager connects to the YubiHSM 2 through a URL to either an HTTP connector or to a direct USB connection:
* :ref:`hsm2-tools-connector-label`: The connector process must have access to the USB connection on the host device
* Direct USB connection: If using the YubiHSM Connector, the YubiHSM Manager process must have access to the USB connections on the host device. See :ref:`hsm2-connect-usb-label` for more details
By default, ``yubihsm-manager`` assumes a the YubiHSM Connector is running and the device is accessible through the URL ``http://127.0.0.1:12345``. A different URL can be specified with the ``--connector`` (``-C``) flag
.. code-block::
# Start the manager with a custom connector URL
$ yubihsm-manager -C http://127.0.0.1:98765
# Start the manager with direct USB connection
$ yubihsm-manager -C yhusb://serial=123456
#. YubiHSM Manager requires opening an authenticated session for most operations. Open an authenticated session using either a password (default) or an ECP256 private key.
In a terminal, run:
.. code-block::
# Password-based session (prompted for password)
$ yubihsm-manager --authkey authkey_id
# Asymmetric session using an ECP256 private key
$ yubihsm-manager --authkey authkey_id --privkey /path/to/ecp256_key.pem
Where
``--authkey`` is the authentication key value. The default is ``1``.
``--privkey`` is the path to a PEM file containing the ECP256 private key corresponding to the public key stored on the YubiHSM and is referenced by the authentication key. If not provided, a password-based session is opened.
For the commands that do not require an authenticated session, run them directly from the command line without opening a session
.. code-block::
# Display device information
$ yubihsm-manager get-device-info
# Display device public key (ECP256)
$ yubihsm-manager get-device-publickey
.. _hsm2-mgr-functions-label:
Main Functionality
===================
To enter the YubiHSM Manager interactive menu, simply launch `yubihsm-manager` without a subcommand. To jump to a
specific section of the interactive menu, include the corresponding subcommand. For example: `yubihsm-manager asym`
.. table::
:class: longtable
+----------------------+--------------------------------------------------------------------------------------------+
| YubiHSM Manager Task | Description |
+======================+============================================================================================+
|-------------**Commands without authentication**-------------------------------------------------------------------|
+----------------------+--------------------------------------------------------------------------------------------+
| get-device-info | Display YubiHSM device information |
+----------------------+--------------------------------------------------------------------------------------------+
| get-device-publickey | Display YubiHSM device public key (ECP256) |
+----------------------+--------------------------------------------------------------------------------------------+
|-------------**Object Browsing**-----------------------------------------------------------------------------------|
+----------------------+--------------------------------------------------------------------------------------------+
| List || List objects stored on the YubiHSM with their properties. Filtered objects are listed in |
| || respective sub-menu |
+----------------------+--------------------------------------------------------------------------------------------+
| Search | Search for specific objects by Object ID, Type or Label |
+----------------------+--------------------------------------------------------------------------------------------+
|-------------**Asymmetric Key Operations (asym)**------------------------------------------------------------------|
+----------------------+--------------------------------------------------------------------------------------------+
| Generate | Generate a new asymmetric key (RSA, EC, Ed25519) on the YubiHSM |
+----------------------+--------------------------------------------------------------------------------------------+
| Import || Import asymmetric private keys or X509 certificates from PEM file into the YubiHSM |
| || Import a wrapped asymmetric object from .yhw file into the YubiHSM |
+----------------------+--------------------------------------------------------------------------------------------+
| Delete | Delete asymmetric private keys or X509 certificates from the YubiHSM |
+----------------------+--------------------------------------------------------------------------------------------+
| Get public key | Retrieve the public key portion of an asymmetric key stored on the YubiHSM |
+----------------------+--------------------------------------------------------------------------------------------+
| Get X509 certificate | Retrieve an X509 certificate stored on the YubiHSM |
+----------------------+--------------------------------------------------------------------------------------------+
| Sign | Sign data using an asymmetric private key stored on the YubiHSM |
+----------------------+--------------------------------------------------------------------------------------------+
| Decrypt | Decrypt data using an RSA private key stored on the YubiHSM |
+----------------------+--------------------------------------------------------------------------------------------+
| Derive ECDH || Derive an ECDH shared secret using an EC private key stored on the YubiHSM and a peer |
| || public key |
+----------------------+--------------------------------------------------------------------------------------------+
|| Sign Attestation | Generate and sign an attestation certificate for a key generated on the YubiHSM |
|| Certificate | |
+----------------------+--------------------------------------------------------------------------------------------+
|-------------**Symmetric Key Operations (sym)**--------------------------------------------------------------------|
+----------------------+--------------------------------------------------------------------------------------------+
| Generate | Generate a new symmetric key (AES) on the YubiHSM |
+----------------------+--------------------------------------------------------------------------------------------+
| Import || Import a symmetric key from a binary file into the YubiHSM |
| || Import a wrapped symmetric key from .yhw file into the YubiHSM |
+----------------------+--------------------------------------------------------------------------------------------+
| Delete | Delete symmetric keys from the YubiHSM |
+----------------------+--------------------------------------------------------------------------------------------+
| Encrypt | Encrypt data using an AES key stored on the YubiHSM and AES-CBC or AES-ECB padding |
+----------------------+--------------------------------------------------------------------------------------------+
| Decrypt | Decrypt data using an AES key stored on the YubiHSM and AES-CBC or AES-ECB padding |
+----------------------+--------------------------------------------------------------------------------------------+
|-------------**Wrap Key Operations (wrap)**------------------------------------------------------------------------|
+----------------------+--------------------------------------------------------------------------------------------+
| Generate || Generate a new AES-CCM wrap key on the YubiHSM |
| || Generate a new RSA private wrap key on the YubiHSM |
+----------------------+--------------------------------------------------------------------------------------------+
| Import || Import an AES-CCM wrap key in HEX format into the YubiHSM with the option to split it |
| || according to Shamir's Secret Sharing scheme |
| || Import an AES-CCM wrap key into the YubiHSM after restoring it from secret shares |
| || Import an RSA private wrap key from a PEM file into the YubiHSM |
| || Import an RSA public wrap key from a PEM file into the YubiHSM |
+----------------------+--------------------------------------------------------------------------------------------+
| Delete | Delete wrap keys from the YubiHSM |
+----------------------+--------------------------------------------------------------------------------------------+
| Get public key || Retrieve the public key portion of an RSA private wrap key stored on the YubiHSM |
| || Retrieve an RSA public wrap key stored on the YubiHSM |
+----------------------+--------------------------------------------------------------------------------------------+
| Export wrapped | Export one or more objects from the device in encrypted form using a wrap key |
+----------------------+--------------------------------------------------------------------------------------------+
| Import wrapped || Import a wrapped object into the YubiHSM. The object must have previously been exported |
| || from a YubiHSM |
+----------------------+--------------------------------------------------------------------------------------------+
|-------------**Authentication Key Management (auth)**--------------------------------------------------------------|
+----------------------+--------------------------------------------------------------------------------------------+
| Setup keys user || Create an authentication key that can only use (a)symmetric keys and wrap keys stored on |
| || the YubiHSM |
+----------------------+--------------------------------------------------------------------------------------------+
| Setup keys admin || Create an authentication key that can only manage (a)symmetric keys and wrap keys stored |
| || on the YubiHSM |
+----------------------+--------------------------------------------------------------------------------------------+
| Setup auditor user | Create an authentication key that can only perform audit functions on the YubiHSM |
+----------------------+--------------------------------------------------------------------------------------------+
| Setup custom user || Create an authentication key with custom capabilities based on the current user's |
| || privileges on the YubiHSM |
+----------------------+--------------------------------------------------------------------------------------------+
+ Delete | Delete authentication keys from the YubiHSM |
+----------------------+--------------------------------------------------------------------------------------------+
|-------------**Device Operations**---------------------------------------------------------------------------------|
+----------------------+--------------------------------------------------------------------------------------------+
| Backup device | Export all exportable objects under wrap to a specified directory |
+----------------------+--------------------------------------------------------------------------------------------+
| Restore device || Read all files ending with .yhw in a specified directory and import the wrapped objects |
| || into the YubiHSM |
+----------------------+--------------------------------------------------------------------------------------------+
| Reset device || Restore the YubiHSM to factory default settings. All data is permanently deleted from the |
| || device and cannot be recovered |
+----------------------+--------------------------------------------------------------------------------------------+
|| Get pseudo random | Get pseudo random bytes generated by the YubiHSM |
|| bytes | |
+----------------------+--------------------------------------------------------------------------------------------+
|-------------**Special Case Operations**---------------------------------------------------------------------------|
+----------------------+--------------------------------------------------------------------------------------------+
| KSP setup | Guided setup of the YubiHSM for Windows KSP/CNG provider |
+----------------------+--------------------------------------------------------------------------------------------+
| SunPKCS11 | Manage asymmetric keys with properties compatible with SunPKCS11 provider in Java |
+----------------------+--------------------------------------------------------------------------------------------+
.. Note:: Symmetric key operations require YubiHSM 2 firmware version 2.3.1 or higher
.. _hsm2-mgr-nav-label:
YubiHSM Manager Navigation
===========================
To select a menu option:
1. Use your keyboard arrow keys to locate and highlight at option.
2. Press [space bar] to toggle between select and unselect.
The check box next to the option is filled when selected and unfilled when unselected.
3. Press [Enter] to accept the selection or the task.
To stop a task in the guided menu:
Press [ESC] from anywhere in the YubiHSM Manager.
* Cancels the current operation.
* Returns to the previous menu.
* If you are in the main menu, it quits YubiHSM Manager.
Sub Commands
-------------
Enter YubiHSM Manager commands in a terminal. Include the appropriate options. The YubiHSM Manager displays the menu driven options, as needed, to complete the command task.
.. table::
:class: longtable
+--------------------------+---------------------------------------------------+
| Command | Description |
+==========================+===================================================+
| ``help`` | Print help text |
+--------------------------+---------------------------------------------------+
| ``get-device-info`` || Display YubiHSM device info |
| || See :ref:`hsm2-cmd-get-device-info-label` |
+--------------------------+---------------------------------------------------+
| ``get-device-publickey`` || Display YubiHSM device public key. Requires |
| || YubiHSM firmware version 2.3.1 or higher. |
| || See :ref:`hsm2-cmd-get-device-public-key-label` |
+--------------------------+---------------------------------------------------+
| ``asym`` | Enter *Asymmetric Key operations* menu |
+--------------------------+---------------------------------------------------+
| ``sym`` | Enter *Symmetric Key operations* menu |
+--------------------------+---------------------------------------------------+
| ``wrap`` | Enter *Wrap Key operations* menu |
+--------------------------+---------------------------------------------------+
| ``auth`` | Enter the *Authentication key operations* menu |
+--------------------------+---------------------------------------------------+
| ``ksp`` || Start guided setup of KSP user for |
| || Windows CNG provider |
+--------------------------+---------------------------------------------------+
| ``sunpkcs11`` || Manage asymmetric keys compatible with |
| || JAVA SunPKCS11 provider |
| || See :ref:`hsm2-pkcs11-java-label` |
+--------------------------+---------------------------------------------------+
| ``reset`` || Reset YubiHSM2 device |
| || See :ref:`hsm2-cmd-reset-device-label` |
+--------------------------+---------------------------------------------------+
Options
--------
.. table::
:class: longtable
+---------------------------------+-------------------------------------------------+
| Option | Description |
+=================================+=================================================+
| ``-h, --help`` | Print help |
+---------------------------------+-------------------------------------------------+
| ``-c, --connector `` | Connector URL. Default: http://127.0.0.1:12345 |
+---------------------------------+-------------------------------------------------+
| ``-k, --authkey `` || Authentication key to open a session with |
| || the device. Default: ``1`` |
+---------------------------------+-------------------------------------------------+
| ``--privkey `` || Path to PEM file containing ECP256 private key |
| || used to open an asymmetric session |
+---------------------------------+-------------------------------------------------+
| ``-p, --password `` | Password to open a session with the device |
+---------------------------------+-------------------------------------------------+
| ``-v, --verbose`` | Produce more debug output |
+---------------------------------+-------------------------------------------------+
| ``-V, --version`` | Print version |
+---------------------------------+-------------------------------------------------+
.. _hsm2-mgr-setup-map-label:
YubiHSM Setup to Manager Mapping
==================================
All YubiHSM Setup operations are available in YubiHSM Manager as follows:
.. table::
:class: longtable
+---------------------------+------------------------------------------+
| YubiHSM Setup subcommand | YubiHSM Manager |
+===========================+==========================================+
| ``dump`` | Device operations menu > Backup device |
+---------------------------+------------------------------------------+
| ``restore`` | Device operations menu > Restore device |
+---------------------------+------------------------------------------+
| ``ksp`` | Special operations menu > KSP setup |
+---------------------------+------------------------------------------+
| ``ejbca`` | Special operations menu > SunPKCS11 |
+---------------------------+------------------------------------------+
| ``reset`` | Device operations menu > Reset device |
+---------------------------+------------------------------------------+
.. Note:: Wrap Key shares obtained through ``yubihsm-setup`` are **not** recoverable in ``yubihsm-manager``.
.. _hsm2-mgr-scripting-label:
Scripting: Record and Execute
==============================
The YubiHSM Manager has a built-in session recording capability. This allows the user to perform operations
interactively once, capture them as a JSON script, and then replay the exact same sequence of operations on other
devices — enabling repeatable, automated provisioning without manual intervention.
The Concept
------------
When recording is enabled, every mutating operation the user performs (key generation, import, deletion, authentication
key creation, wrap/unwrap, backup, restore) is captured as a structured entry in a JSON script file. The script also
records the session metadata (connector URL and authentication key ID). The session metadata can be overridden by the
commandline options.
Example of a typical workflow:
1. Develop your own provisioning procedure interactively on a test device with ``--record`` enabled.
2. Review and edit the generated JSON script. You can hand-edit the file to adjust object IDs, labels, or add/remove operations.
3. Replay the script on production devices using ``--exec``, providing any prompted secrets at execution time.
4. For fleet provisioning, combine ``--exec`` with ``--mask sensitive`` (default) so that secrets are never stored on disk but all structural parameters are automated.
Recordable Operations
----------------------
Only operations that alter the content of the YubiHSM are recorded in the script:
.. table::
:class: longtable
+---------------------+-----------------------------------------------------+
| Recordable Operation| Description |
+=====================+=====================================================+
| Generate object || Generate an asymmetric key, symmetric key, wrap |
| || key, or self-signed certificate |
+---------------------+-----------------------------------------------------+
| Import object || Import a private key, certificate, wrap key or |
| || symmetric key from a file or hex value |
+---------------------+-----------------------------------------------------+
|| Create || Create an authentication key (password-derived |
|| authentication key || or ECP256 public-key-based) |
+---------------------+-----------------------------------------------------+
| Delete object | Delete an object |
+---------------------+-----------------------------------------------------+
|| Export | Export an object under wrap |
|| wrapped object | |
+---------------------+-----------------------------------------------------+
|| Import | Import a previously wrapped object |
|| wrapped object | |
+---------------------+-----------------------------------------------------+
| Backup device | Export all exportable objects under wrap |
+---------------------+-----------------------------------------------------+
| Restore device | Restore all .yhw files from a backup directory |
+---------------------+-----------------------------------------------------+
Recording a Session
--------------------
To record, start ``yubihsm-manager`` with the ``--record`` (``-r``) flag:
While recording is active, use ``yubihsm-manager`` normally. Each recordable operation is captured in the script file in
real time. The script file is flushed after every operation, so even if the session is interrupted, all previously
completed operations are preserved in the script.
If ``--script-path`` is not provided, the script is saved to ``yubihsm-manager-.json`` in the current
directory.
A mask level controls which values are stored in the script in plain text vs. which values are replaced with a
placeholder that prompts for a value during script execution:
.. table::
:class: longtable
+-----------------+---------------------------------------------------+
| Mask Level | Behavior |
+=================+===================================================+
|| ``sensitive`` || Passwords, raw key material, and private key |
|| (default) || file paths are replaced with ```` |
+-----------------+---------------------------------------------------+
| ``all`` || All user-provided values are replaced with |
| || ````. The operator must provide every |
| || value interactively during script execution |
+-----------------+---------------------------------------------------+
| ``none`` || All values are stored in plain text, including |
| || raw key material and passwords. |
| || **Use with caution** |
+-----------------+---------------------------------------------------+
Executing a Script
------------------
To replay a previously recorded script, start ``yubihsm-manager`` with the ``--exec /path/to/script.json`` (``-e``)
option. During execution, operations are replayed sequentially and progress is displayed step-by-step.
If any operation fails, the default behavior is to stop immediately and report the error. With the
``--continue-on-error`` flag, failed operations are warned and skipped, and a summary of errors is displayed at the end.
For any value that was masked as ```` during recording, the operator is prompted interactively during execution
to provide the value (e.g., entering a password, providing a file path to a PEM key, or supplying hex-encoded key
material).
Scripting CLI Reference
------------------------
.. table::
:class: longtable
+-------------------------------------+------------------------------------------------------------+
| Command option | Description |
+=====================================+============================================================+
| ``-r, --record`` | Record session operations in a script for later execution. |
+-------------------------------------+------------------------------------------------------------+
| ``-e, --exec `` | Execute operations from a recorded script file. |
+-------------------------------------+------------------------------------------------------------+
| ``-s, --script-path `` || Path to a new script file. Use with ``--record``. |
| || ``./yubihsm-manager_.json`` if not set. |
+-------------------------------------+------------------------------------------------------------+
| ``--mask `` || Set masking level for recorded script. Masked values are |
| || prompted during script execution. Default: ``sensitive`` |
| || Possible values: ``sensitive``, ``all``, ``none`` |
+-------------------------------------+------------------------------------------------------------+
| ``--continue-on-error`` || Warn and skip failed operations during script execution |
| || instead of exiting. |
+-------------------------------------+------------------------------------------------------------+