Base ykman Command

The base commands do not apply to any specific protocol. However, they do apply to the different connection methods such as USB and NFC.

See the bottom of this page for acronyms and their definitions.

ykman [OPTIONS] COMMAND [ARGS]…

Configure your YubiKey via the command line.

Examples

List connected YubiKeys, only output serial number:
```
$ ykman list --serials
0123456
```

Show information about the YubiKey with serial number 0123456:

$ ykman --device 0123456 info

Device type: YubiKey 5C Nano
Serial number: 0123456
Firmware version: 5.7.1
Form factor: Nano (USB-C)
Enabled USB interfaces: OTP, FIDO, CCID

Applications
Yubico OTP         Enabled
FIDO U2F           Enabled
FIDO2              Enabled
OATH               Enabled
PIV                Enabled
OpenPGP            Enabled
YubiHSM Auth       Enabled

Options

Option	Description
`-h, --help`	Show this message and exit.
`-c, --scp-sd KID KVN`	Specify which key the YubiKey is using to authenticate. Option added in ykman version 5.7.1 Hidden option.
`-d, --device SERIAL`	Specify YubiKey to interact with by serial number.
`--diagnose`	Show diagnostics information for troubleshooting.
`--full-help`	Show `--help`, plus hidden commands, and exit.
`--log-file FILE`	Write logs to a given FILE instead of printing to stderr. Requires `--log-level`.
`-l, --log-level [error\|` `warning\|info\|debug\|traffic]`	Enable logging at given verbosity level.
`-o, --scp-oce KID KVN`	Specify which key the OCE is using to authenticate. Option added in ykman version 5.7.1 Hidden option.
`-p, --scp-password PASSWORD`	Specify a password required to access the `--scp` file, if needed. Option added in ykman version 5.5
`-r, --reader NAME`	Specify a YubiKey by smart card reader. Cannot be used with `--device` or `list`.
`-s, --scp CRED`	Specify private key and certificate chain for secure messaging. Can be used multiple times to provide key and certificates in multiple files, (private key, certificates in leaf-last order), or SCP03 keys in hex separated by colon (:) `K-ENC:K-MAC[:K-DEK]` Option added in ykman version 5.5
`-t, --scp-ca FILENAME`	Specify the CA to use to verify the SCP11 card key (CA-KLCC) Option added in ykman version 5.5
`-v, --version`	Show version information about the app [ykman].

Commands

Command	Description
`apdu`	Execute arbitrary APDUs. Hidden command.
`config`	Configure the YubiKey. Enable/Disable applications.
`fido`	Manage the FIDO Commands.
`hsmauth`	Manage the HSMauth Commands.
`info`	Show general information.
`list`	List connected YubiKeys.
`oath`	Manage the OATH Commands.
`openpgp`	Manage the OpenPGP Commands.
`otp`	Manage the OTP Commands.
`piv`	Manage the PIV Commands.
`script`	Run a Python script.
`sd`	Manage the Security Domain application, which holds keys for SCP. Hidden command.

ykman info [OPTIONS]

Show general information. Displays information about the connected YubiKey such as serial number, firmware version, capabilities, etc.

Options

Option	Description
`-h, --help`	Show this message and exit.
`-c, --check-fips`	Check if YubiKey is in FIPS-approved mode. Available on YubiKey 4 FIPS only.

FIPS-Approved Mode

NIST classified the YubiKey 5 Series FIPS as “composite authenticators”. As such, no device in that series can be taken out of the FIPS-approved mode after initialization without zeroizing the function. This means that once the YubiKey is correctly configured, it remains in the correct configuration. This is what renders the --check-fips command unnecessary for YubiKey 5 FIPS Series keys. As long as the crypto officer ensures that the YubiKey 5 Series FIPS devices are correctly configured at initialization, they remain in FIPS-approved mode.

Example

$ ./ykman info
Device type: YubiKey 5Ci FIPS
Serial number: 31234067
Firmware version: 5.7.3
Form factor: Keychain (USB-C, Lightning)
Enabled USB interfaces: OTP, FIDO, CCID
PIN complexity is enforced

Applications
Yubico OTP   Enabled
FIDO U2F     Not available
FIDO2        Enabled
OATH         Enabled
PIV          Enabled
OpenPGP      Enabled
YubiHSM Auth Enabled

FIPS approved applications
FIDO2:        False
OATH:         False
PIV:          False
OpenPGP:      False
YubiHSM Auth: False

ykman list [OPTIONS]

List connected YubiKeys.

Options

Option	Description
`-h, --help`	Show this message and exit.
`-r, --readers`	List available smart card readers.
`-s, --serials`	Output only serial numbers of the connected YubiKeys, one per line. Devices without serial numbers are not listed.

ykman script [OPTIONS] FILE [ARGUMENTS]

Run a Python script.

Warning

Never run a script without fully understanding what it does! Scripts are very powerful, and have the power to harm to both your YubiKey and your computer. ONLY run scripts that you fully trust!

Arguments can be passed to the script by adding them after the end of the command. These are accessible inside the script as sys.argv, with the script name as the initial value. For more information on scripting, see sys.argv in the Python.org documentation.

Examples

Run the file myscript.py, passing arguments 123456 and indata.csv:

$ ykman script myscript.py 123456 indata.csv

Options

Option	Description
`-h, --help`	Show this message and exit.
`-f, --force`	Confirm the action without prompting.
`-s, --site-dir DIR`	Specify additional path(s) from which to load Python modules.

Acronyms

3DES:	Triple Data Encryption Algorithm
AES:	Advanced Encryption Standard
CCC:	Card Capability Container
CCID:	Chip card interface device, a USB protocol for a smartcard.
CHUID:	Card Holder Unique ID
CN:	Common name
CSR:	Certificate Signing Request
ECC:	Elliptic curve cryptography
FIDO:	Fast Identity Online
FIPS:	Federal Information Processing Standards (US government) covering codes and encryption standards.
HMAC:	Hash-based message authentication code
HOTP:	HMAC-based One-Time Password algorithm
OATH:	The Initiative for Open Authentication is an organization that specifies two open authentication standards, TOTP and HOTP
OTP:	One-Time Password
PUK:	PIN Unlock Key
`stdin`:	standard input - usually keyboard or CLI instructions
`stdout`:	standard output - usually print to screen
TOTP:	Time-based One-Time Password algorithm
X.509:	The standard defining the format of a public key certificate