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.

Running YubiHSM Manager

YubiHSM Manager runs on Windows, macOS, and Linux.

1. 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.

2. YubiHSM Manager connects to the YubiHSM 2 through a URL to either an HTTP connector or to a direct USB connection:

   • YubiHSM 2 Connector: 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 USB Access to YubiHSM 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

   # 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
   

3. 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:

   # 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

   # Display device information
   $ yubihsm-manager get-device-info
   
   # Display device public key (ECP256)
   $ yubihsm-manager get-device-publickey
   

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

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 Certificate	Generate and sign an attestation certificate for a key generated on the YubiHSM
————-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 bytes	Get pseudo random bytes generated by the YubiHSM
————-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

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.

Command	Description
help	Print help text
get-device-info	Display YubiHSM device info See GET DEVICE INFO Command
get-device-publickey	Display YubiHSM device public key. Requires YubiHSM firmware version 2.3.1 or higher. See GET DEVICE PUBLIC KEY Command
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 PKCS#11 with JAVA
reset	Reset YubiHSM2 device See RESET DEVICE Command

Options

Option	Description
-h, --help	Print help
-c, --connector <connector>	Connector URL. Default: http://127.0.0.1:12345
-k, --authkey <authkey>	Authentication key to open a session with the device. Default: 1
--privkey <privkey>	Path to PEM file containing ECP256 private key used to open an asymmetric session
-p, --password <password>	Password to open a session with the device
-v, --verbose	Produce more debug output
-V, --version	Print version

YubiHSM Setup to Manager Mapping

All YubiHSM Setup operations are available in YubiHSM Manager as follows:

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.

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:

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 authentication key	Create an authentication key (password-derived or ECP256 public-key-based)
Delete object	Delete an object
Export wrapped object	Export an object under wrap
Import wrapped object	Import a previously 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-<YYYYMMDD-HHMMSS>.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:

Mask Level	Behavior
sensitive (default)	Passwords, raw key material, and private key file paths are replaced with <PROMPT>
all	All user-provided values are replaced with <PROMPT>. 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 <PROMPT> 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

Command option	Description
-r, --record	Record session operations in a script for later execution.
-e, --exec <file>	Execute operations from a recorded script file.
-s, --script-path <script_name>	Path to a new script file. Use with --record. ./yubihsm-manager_<timestamp>.json if not set.
--mask <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.