YubiHSM 2 Shell

The yubihsm-shell tool is a command-line tool for interacting directly with a YubiHSM 2 device. It is a thin wrapper around libyubihsm and exposes most of its functionality either interactively at a prompt or non-interactively as a scriptable command-line utility.

yubihsm-shell is the primary tool for advanced user to administer, configure, and test a YubiHSM 2. It is suitable for both one-off administrative tasks and for integration into automation pipelines.

Examples of commands can be found in the YubiHSM Command Reference reference. 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.

yubihsm-shell communicates with the YubiHSM 2 through a connector specified using the --connector option. If no connector is specified, it defaults to http://localhost:12345, which assumes the yubihsm-connector service is running on the same host. To use direct USB access instead, use the yhusb:// URL scheme. For example:

$ yubihsm-shell --connector yhusb://
$ yubihsm-shell --connector yhusb://serial=12345678

Modes of Operation

yubihsm-shell supports two modes of operation: interactive and command-line (non-interactive).

Interactive Mode

Interactive mode is started by running yubihsm-shell with no --action argument. It presents a yubihsm> prompt and supports tab completion (on Linux and macOS) and standard terminal shortcuts such as Ctrl-P, Ctrl-N, Ctrl-A, and Ctrl-E.

$ yubihsm-shell
yubihsm>

Within interactive mode, a connection to the connector and an authenticated session must be opened before most commands can be used. For example, the following commands connect to the default connector and open a session with Authentication Key ID 1 and password password:

yubihsm> connect
yubihsm> session open 1 password
Created session 0

Help on all available commands is obtained by running:

yubihsm> help

Help on a specific command is obtained by running:

yubihsm> help <COMMAND>

Debug output can be enabled with the command debug <level> where level is one of all, crypto, error, info, intermediate, none, or raw. For example:

yubihsm> debug all

Input and output formats can be changed per session. Available formats are PEM, base64, binary, hex, password, and default. For example:

yubihsm> set informat base64
yubihsm> set outformat hex

When help is run on a specific command in interactive mode, yubihsm-shell displays the command’s argument specification. For example:

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

Each comma-separated entry is one argument. In the example above there are five arguments: e:session, w:key_id, a:algorithm, i:data=-, and F:out=-. Each argument has the form type:name[=default]. The part before the colon is a single letter indicating the type of value expected. The part after the colon is a descriptive name for the argument. If an = follows the name, the value after it is the default that is used if the argument is omitted. The table below describes the different argument types and their expected values.

Argument Identifier	Type	Description
`a`	Algorithm	An algorithm in string form (ex: `ecp256`). The full list is available with `list algorithms`
`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`) or * the special string `all` to indicate all capabilities The full list is available with `list capabilities`
`d`	Domains	A list of Domains, either in hex (ex: `0xffff`) or string form (ex: `3,5,14`)
`I`	Format	An input or output format specifier (ex: `base64`)
`i`	Input data	Input data: a filename, a literal value, or `-` to read from standard input (stdin)
`u`	Unsigned number	A 32-bit unsigned number (hex or dec), e.g. a nonce or a count
`o`	Option	A device-global option in string form (ex: `force-audit`)
`F`	Output filename	A filename to write output to, or `-` to write to standard output (stdout)
`e`	Session	The ID of an already-established Session. Sessions are opened with `session open` and referred to by their numeric ID (e.g. `0`)
`s`	String	A generic string, e.g. a label. (use quotes for strings that include white spaces)
`t`	Object Type	An Object Type in string form (ex: `asymmetric-key`) The full list is available with `list types`
`w`	Word (unsigned short)	A 16-bit unsigned number (hex or dec), typically an Object ID or similar identifier. Object IDs must be in the range `1-65535` (`0x0001-0xffff`)

Command-line (Non-interactive) Mode

In non-interactive mode, a single action is specified via the argument --action (or -a) along with all required parameters as flags. This mode is well suited for scripting and automation.

Authentication is provided directly on the command line using --password (or -p), along with --authkey to specify which Authentication Key ID to use.

A full list of options and actions is available by running:

$ yubihsm-shell --help

Example:

The following generates an RSA-2048 Asymmetric Key with label Signing-Key, Object ID 10, in Domain 1, with the sign-pss capability:

$ yubihsm-shell -a generate-asymmetric-key \
                -i 10 \
                -l "Signing-Key" \
                -d 1 \
                -c sign-pss \
                -A rsa2048

Note

Not all commands are available in command-line mode. For commands that are not available in command-line mode, use the interactive mode instead.