HSMauth Commands

For a full description of YubiHSM Auth, see the YubiKey 5 Series Technical Manual, Protocols and Applications > YubiHSM Auth chapter.

Enable or Disable YubiHSM Auth on a YubiKey

This section includes the expected output and testing methods.

YubiHSM Auth is available as of firmware version 5.4.X and is disabled by default.

Enable YubiHSM Auth by running:

ykman config usb --enable HSMAUTH
YubiHSM Auth successfully enabled.

Test enablement by connecting to the YubiHSM with YubiHSM-Shell:

yubihsm> session ykopen 1 "default key" "my secret"
Session authenticated to YubiHSM2.

Disable YubiHSM Auth by running:

ykman config usb --disable HSMAUTH
YubiHSM Auth successfully disabled.

Test disablement by connecting to the YubiHSM with YubiHSM-Shell:

yubihsm> session ykopen 1 "default key" "my secret"
No access to the YubiKey application YubiHSM Auth.

ykman hsmauth [OPTIONS] COMMAND [ARGS]…

Manage the YubiHSM Auth application

Options

Option	Description
`-h, --help`	Show this message and exit.

Commands

Command	Description
`access`	Manage Management Key for YubiHSM Auth.
`credentials`	Manage YubiHSM Auth credentials.
`info`	Display general status of the YubiHSM Auth application.
`reset`	Reset all YubiHSM Auth data.

ykman hsmauth access [OPTIONS] COMMAND [ARGS]…

Manage the Management Key for YubiHSM Auth.

Options

Option	Description
`-h, --help`	Show this message and exit.

Commands

Command	Description
`change-management-password`	Change the Management key.

ykman hsmauth access change-management-password

Change the Management key.

Allows you to change the Management key. This is required to add and delete YubiHSM Auth credentials stored on the YubiKey.

ykman hsmauth access change-management-password supersedes ykman hsmauth access change-management-key, in ykman version 5.5.

Options

Option	Description
`-h, --help`	Show this message and exit.
`-m, --management-password` `TEXT`	Current management key. Default: b’x00x00x00x00x00x00x00 x00x00x00x00x00x00x00x00x00’
`-n, --new-management-password` `TEXT`	A new management key to set.

ykman hsmauth credentials [OPTIONS] COMMAND [ARGS]…

Manage YubiHSM Auth credentials.

Options

Option	Description
`-h, --help`	Show this message and exit.

Commands

Command	Description
`delete`	Delete a credential.
`derive`	Import a symmetric credential derived from a password.
`export`	Export the public key corresponding to an asymmetric credential.
`generate`	Generate an asymmetric credential.
`import`	Import an asymmetric credential.
`list`	List all credentials.
`symmetric`	Import a symmetric credential.

ykman hsmauth credentials delete [OPTIONS] LABEL

Delete a credential.

This deletes a YubiHSM Auth credential from the YubiKey.

Arguments

Argument	Description
`LABEL`	A label to match a single credential, as shown in `credential list`.

Options

Option	Description
`-h, --help`	Show this message and exit.
`-m, --management-password,` `--management-key TEXT`	The Management password.
`-f, --force`	Confirm the action without prompting.

ykman hsmauth credentials derive [OPTIONS] LABEL

Import a symmetric credential derived from a password.

This imports a symmetric YubiHSM Auth credential by deriving ENC and MAC keys from a password.

Arguments

Argument	Description
`LABEL`	A label for the YubiHSM Auth credential.

Options

Option	Description
`-h, --help`	Show this message and exit.
`-d, --derivation-password` `TEXT`	Derivation password for ENC and MAC keys.
`-c, --credential-password` `TEXT`	Password to protect credential.
`-m, --management-password,` `--management-key TEXT`	The management password.
`-t, --touch`	Requires touch on YubiKey to access credential.

ykman hsmauth credentials export [OPTIONS] LABEL PUBLIC-KEY

Export the public key corresponding to an asymmetric credential.

This exports the long-term public key corresponding to the asymmetric YubiHSM Auth credential stored on the YubiKey.

Arguments

Argument	Description
`LABEL`	A label for the YubiHSM Auth credential.
`PUBLIC-KEY`	File to write the public key to. Use `-` to use `stdout`.

Options

Option	Description
`-h, --help`	Show this message and exit.
`-F, --format [PEM\|DER]`	Encoding format. Default: PEM

ykman hsmauth credentials generate [OPTIONS] LABEL

Generate an asymmetric credential.

This generates an asymmetric YubiHSM Auth credential (private key) on the YubiKey.

Arguments

Argument	Description
`LABEL`	A label for the YubiHSM Auth credential.

Options

Option	Description
`-h, --help`	Show this message and exit.
`-c, --credential-password TEXT`	Password to protect credential.
`-m, --management-password,` `--management-key TEXT`	The management password.
`-t, --touch`	Requires touch on YubiKey to access credential.

ykman hsmauth credentials import [OPTIONS] LABEL PRIVATE-KEY

Import an asymmetric credential.

This imports a private key as an asymmetric YubiHSM Auth credential to the YubiKey.

Arguments

Argument	Description
`LABEL`	A label for the YubiHSM Auth credential.
`PRIVATE-KEY`	File containing the private key. Use `-` to use `stdin`.

Options

Option	Description
`-h, --help`	Show this message and exit.
`-c, --credential-password TEXT`	Password to protect credential.
`-m, --management-password,` `--management-key TEXT`	The management password.
`-p, --password TEXT`	Password used to decrypt the private key.
`-t, --touch`	Requires touch on YubiKey to access credential.

ykman hsmauth credentials list [OPTIONS]

List all credentials stored on the YubiKey.

Options

Option	Description
`-h, --help`	Show this message and exit.

ykman hsmauth credentials symmetric [OPTIONS] LABEL

Import a symmetric credential.

This imports an encryption and mac key as a symmetric YubiHSM Auth credential on the YubiKey.

Arguments

Argument	Description
`LABEL`	A label for the YubiHSM Auth credential.

Options

Option	Description
`-h, --help`	Show this message and exit.
`-c, --credential-password TEXT`	Password to protect credential.
`-E, --enc-key TEXT`	The ENC key.
`-g, --generate`	Generate a random encryption and MAC key.
`-m, --management-password,` `--management-key TEXT`	The management password.
`-M, --mac-key TEXT`	The MAC key.
`-t, --touch`	Requires touch on YubiKey to access credential.

ykman hsmauth info [OPTIONS]

Display general status of the YubiHSM Auth application.

Options

Option	Description
`-h, --help`	Show this message and exit.

ykman hsmauth reset [OPTIONS]

Reset all YubiHSM Auth data.

This action wipes all data and restores factory setting for the YubiHSM Auth application on the YubiKey.

Options

Option	Description
`-h, --help`	Show this message and exit.
`-f, --force`	Confirm the action without prompting.