LinuxCommandLibrary

ykman

Manage and configure YubiKey devices

TLDR

Display general information about a YubiKey (serial number, firmware version, capabilities, etc.)

$ ykman info
copy

List connected YubiKeys with short, one-line descriptions (including the serial number)
$ ykman list
copy

View documentation for enabling and disabling applications
$ tldr ykman config
copy

View documentation for managing the FIDO applications
$ tldr ykman fido
copy

View documentation for managing the OATH application
$ tldr ykman oath
copy

View documentation for managing the OpenPGP application
$ tldr ykman openpgp
copy

SYNOPSIS

ykman [GLOBAL_OPTIONS] COMMAND [COMMAND_OPTIONS] [ARGUMENTS]

Examples:
ykman info
ykman oath accounts add 'MyService' 'JBSWY3DPEHPK3PXP'
ykman piv change-pin

PARAMETERS

-h, --help
    Show a help message for ykman or a specific subcommand.

--version
    Show the version information for ykman.

-d, --device SERIAL
    Specify a YubiKey by its serial number to operate on, useful when multiple YubiKeys are connected.

-l, --log-level LEVEL
    Set the logging verbosity. Possible levels include debug, info, warning, error, or critical.

-v, --verbose
    Enable verbose output, providing more detailed information during command execution.

--full-help
    Show comprehensive help, including less common commands and advanced options not always visible with --help.

DESCRIPTION

ykman is the official command-line tool for managing and configuring YubiKey hardware security keys. It provides a comprehensive interface for interacting with various YubiKey applications and features, including One-Time Password (OTP), FIDO2/WebAuthn, PIV (Smart Card), OATH (TOTP/HOTP), and OpenPGP. Users can perform tasks such as retrieving device information, configuring global settings, provisioning credentials, resetting applications, changing PINs, and managing USB interfaces. ykman is essential for power users, developers, and administrators who need fine-grained control over their YubiKeys, enabling automation and scripting of common management operations. Its modular design, utilizing subcommands, makes it versatile for different YubiKey functionalities.

CAVEATS

Some operations, such as factory resetting the YubiKey or resetting specific applications, are destructive and irreversible. Always back up any critical data or credentials before performing such actions. Proper system permissions (e.g., udev rules or administrator/root privileges) might be required for ykman to access the YubiKey device, especially for write operations. Not all ykman features are available on all YubiKey models or firmware versions; consult YubiKey documentation for specific compatibility details.

KEY SUBCOMMANDS

ykman's functionality is organized into several key subcommands, each managing a specific aspect or application of the YubiKey:
info: Displays general information about the connected YubiKey.
config: Configures global YubiKey settings, such as USB interfaces and device capabilities.
otp: Manages Yubico OTP credentials, including programming slots.
oath: Manages OATH credentials for Yubico Authenticator (TOTP/HOTP).
piv: Manages the PIV (Personal Identity Verification) smart card application, including certificates and PINs.
openpgp: Manages the OpenPGP smart card application, including keys and administrative settings.
fido2: Manages FIDO2/WebAuthn credentials and settings.
u2f: Manages U2F (Universal 2nd Factor) settings.
calibrate: Performs a touch calibration on the YubiKey (for models with touch sensors).
usb: Configures the USB interfaces enabled on the YubiKey.

SECURITY CONSIDERATIONS

When using ykman, particularly with commands that modify or reset the device, exercise extreme caution. Ensure you understand the implications of each command, especially those involving sensitive data, cryptographic keys, or device resets. Always use ykman from a trusted and secure environment to prevent unauthorized access or manipulation of your YubiKey. For new devices, it's advisable to factory reset and change default PINs before use.

HISTORY

ykman is developed and maintained by Yubico, the creators of the YubiKey. It serves as the primary and official command-line interface for YubiKey management. Over time, it has evolved to consolidate various functionalities into a single, cohesive tool, streamlining the process of configuring and interacting with different YubiKey applications. Its continuous development reflects the expanding capabilities of YubiKeys and the need for a robust, scriptable management utility that integrates seamlessly with operating systems.

SEE ALSO

gpg(1), oathtool(1), openssl(1), udev(7)

Copied to clipboard