YubiHSM Shell Reference

The yubihsm-shell is the administrative and testing tool you can use to interact with and configure the YubiHSM 2 device.

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 Command reference.

Note

For operations that take input data (from command line or file), releases prior to and including the current yubihsm2-sdk release have a size limit - 4kb in interactive mode, or 8kb in non-interactive mode.

How to Use the 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).

Possible Command Types

Arg Type Description
u number A generic (hex or dec) unsigned number
w word A generic (hex or dec) 16-bit unsigned number
b byte A generic (hex or dec) 8-bit unsigned number
i input data Input data, generally defaults to standard input
F output filename Output file name, generally defaults to standard output
s string A generic string (use quotes for strings including white spaces)
e session The ID of an already-established Session
d domains A list of Domains, either in hex (ex: 0xffff) or string form (ex: 3,5,14)
c capabilities A list of Capabilities in either form: hex (ex: 0xffffffffffffffff) or string (ex: sign-pkcs,sign-pss, get-log-entries)
a algorithm An algorithm in string form (ex: eccp256)
t type An Object Type in string form (ex: Asymmetric)
o option A device-global option in string form (ex: force-audit)
I format A format specifier in string form (ex: base64)

Data Format

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

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.

Enabling Debug

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.