ykman-oath

Display general information about the OATH application

$ ykman oath info

$ ykman oath access change

$ ykman oath accounts add [[-i|--issuer]] [issuer] [name]

$ ykman oath accounts list

$ ykman oath accounts code [keyword]

$ ykman oath accounts rename [keyword] [issuer:name|name]

$ ykman oath accounts delete [keyword]

$ ykman oath reset

ykman oath <subcommand> [<options>] [<arguments>]

Common subcommands:
ykman oath accounts add <name> [<secret>]
ykman oath accounts delete <name>
ykman oath accounts list
ykman oath code [<name>]
ykman oath info
ykman oath reset

-h, --help
    Show help message and exit for the command or subcommand.

-V, --version
    Show program's version number and exit.

-d, --device <serial>
    Select a specific YubiKey device by its serial number if multiple are connected.

-l, --log-level <level>
    Set the log level for output (e.g., DEBUG, INFO, WARNING, ERROR, CRITICAL).

-p, --password
    Prompt for a password to unlock the OATH application on the YubiKey, if set.

accounts add <name> [<secret>]
    Adds a new OATH credential to the YubiKey.
<name>: The identifier for the credential (e.g., 'Google:user@example.com').
[<secret>]: The base32-encoded OATH secret. If omitted, the tool will prompt for it.

--totp
    Used with 'accounts add' to specify the credential is TOTP (Time-based One-Time Password). This is the default if neither --totp nor --hotp is specified.

--hotp
    Used with 'accounts add' to specify the credential is HOTP (HMAC-based One-Time Password).

-d, --digits <digits>
    Used with 'accounts add' to specify the number of digits for the generated code (6 or 8, default is 6).

-i, --period <seconds>
    Used with 'accounts add' for TOTP credentials to set the period in seconds (default is 30).

-c, --counter <counter>
    Used with 'accounts add' for HOTP credentials to set the initial counter value (default is 0).

-s, --touch-required
    Used with 'accounts add' to configure the credential to require a physical touch on the YubiKey to generate a code.

accounts delete <name>
    Deletes an OATH credential specified by its name from the YubiKey.

accounts list
    Lists all OATH credentials stored on the YubiKey.

-s, --single
    Used with 'accounts list' to only show single codes that do not require touch.

-a, --all
    Used with 'accounts list' to show all accounts, including those requiring touch.

code [<name>]
    Generates and prints the OATH code for a specified credential. If <name> is omitted and multiple accounts exist, it may prompt for selection.

info
    Displays general information about the OATH application on the connected YubiKey, such as version and password status.

reset
    Resets the OATH application on the YubiKey, permanently deleting all stored OATH credentials and clearing any set password.

ykman-oath is a powerful subcommand of the ykman (YubiKey Manager) tool, designed specifically for interacting with and managing OATH (Open AuTHentication) applications on a YubiKey. OATH applications typically involve Time-based One-Time Passwords (TOTP) and HMAC-based One-Time Passwords (HOTP), which are widely used for two-factor authentication (2FA). This command allows users to list, add, delete, and generate codes for these credentials directly from the command line.

It provides a convenient way to provision and use 2FA tokens stored securely on a YubiKey, integrating seamlessly into command-line workflows. It abstracts the complexities of the underlying CCID interface, offering a user-friendly interface for security-conscious individuals and system administrators. Whether you need to enroll a new TOTP secret for an online service or generate a one-time code for login, ykman-oath streamlines the process.

Resetting the OATH application using ykman oath reset will permanently delete all OATH credentials stored on your YubiKey. Ensure you have backups of all your secrets before performing this action.

The YubiKey has a limited number of slots for OATH credentials (typically 32).

Accessing the YubiKey with ykman often requires appropriate USB access permissions, which may necessitate running the command with sudo or configuring udev rules.

The OATH application on a YubiKey can be protected with a password. If a password is set, operations like listing accounts or generating codes will require you to provide it, either via the --password flag or by being prompted.

For enhanced security, individual OATH credentials can be configured to require a physical touch on the YubiKey before a code is generated. This prevents unauthorized code generation even if your computer's software environment is compromised.

When adding new OATH credentials, the secret keys are typically provided in Base32 encoding. Many services that offer TOTP/HOTP secrets provide them in this format, which ykman-oath expects.

The ykman tool, and consequently its oath subcommand, emerged as the official command-line interface for managing YubiKey devices. Prior to ykman, users often relied on separate, less integrated tools or third-party solutions to manage different YubiKey applications like PIV, OATH, or FIDO. The development of ykman aimed to provide a unified, user-friendly, and comprehensive toolset.

The oath subcommand specifically consolidates the functionality for provisioning and using HOTP/TOTP credentials, making the YubiKey an even more versatile hardware authenticator. Its continuous development reflects the evolving standards of multi-factor authentication and the increasing demand for seamless hardware security integration.

ykman(1), gpg(1), ssh-keygen(1), oath-toolkit(1)