How to Use the Command 'ykman oath' (with examples)

The ‘ykman oath’ command is a part of the YubiKey Manager CLI toolset that facilitates managing the OATH (Open AuTHentication) application on YubiKeys. This command helps users oversee different aspects of their OATH configurations, such as viewing application information, managing account credentials, and modifying security settings. YubiKeys are hardware authentication devices produced by Yubico that offer enhanced security for various online accounts, and understanding how to leverage ‘ykman oath’ effectively can help users maintain and manipulate their multi-factor authentication settings with ease.

Use Case 1: Display General Information About the OATH Application

Code:

ykman oath info

Motivation:

Understanding the general information about the OATH application on your YubiKey is essential for users who are either new to the YubiKey platform or need to confirm their current configuration. This can provide crucial insights into the setup, available features, and any imposed restrictions of the OATH application.

Explanation:

• ykman: Invokes the YubiKey Manager CLI tool.
• oath: Specifies that the command is related to the OATH application.
• info: Requests general information about the current OATH configuration on the YubiKey.

Example Output:

OATH version: 4.3.7
Password protection: enabled
Number of accounts: 5

Use Case 2: Change the Password Used to Protect OATH Accounts

Code:

ykman oath access change

Motivation:

Changing the password for OATH accounts is crucial for maintaining the security and integrity of your YubiKey’s authentication functions. It might be necessary to change the password to follow security protocols, respond to potential breaches, or simply update credentials periodically as part of regular security maintenance.

Explanation:

• ykman: Calls the YubiKey Manager CLI.
• oath: Indicates operations related to OATH.
• access: Refers to permissions or credentials related tasks.
• change: Specifies the action to update the existing password.

Example Output:

Enter your new password: 
Confirm your new password: 
Password changed successfully.

Use Case 3: Add a New Account

Code:

ykman oath accounts add --issuer Google mygoogleaccount

Motivation:

Adding a new account is a fundamental task when setting up multi-factor authentication for an internet account that supports OTP (One-Time Passwords). Incorporating an issuer’s information can enhance organization, especially for users managing multiple accounts from various services.

Explanation:

• ykman: Calls the YubiKey Manager CLI tool.
• oath: Pertains to the OATH service on the YubiKey.
• accounts: Delivers actions associated with account handling.
• add: Signifies the action to incorporate a new account.
• --issuer Google: Optional; denotes the organization or service provider (in this example, Google).
• mygoogleaccount: Represents the account name chosen by the user for identification purposes.

Example Output:

Account added successfully for issuer Google: mygoogleaccount.

Use Case 4: List All Accounts

Code:

ykman oath accounts list

Motivation:

Listing all OATH accounts is necessary for users who wish to maintain an overview of their existing authentication setups. It provides a complete view of all currently configured accounts, which is valuable for both ensuring everything is correctly set up and managing multiple accounts efficiently.

Explanation:

• ykman: Invokes the YubiKey Manager CLI tool.
• oath: Specifies usage related to the OATH applications.
• accounts: Indicates actions specific to account handling.
• list: Requests a display of all current accounts along with their issuers.

Example Output:

Google: mygoogleaccount
Facebook: myfacebookaccount
Twitter: mytwitteraccount

Use Case 5: List All Accounts with Their Current TOTP/HOTP Codes

Code:

ykman oath accounts code 

Motivation:

There might be instances where a user needs to quickly access the current TOTP or HOTP codes for their accounts to log into a service that requires these one-time passwords for verification. This command provides the ability to view all current authentication codes directly from the command line.

Explanation:

• ykman: Initiates the YubiKey Manager CLI interaction.
• oath: Refers to the OATH service on the YubiKey.
• accounts: Pertains to actions regarding account management.
• code: Instructs the tool to list temporary or hardware protected OTPs for accounts.

Example Output:

Google: mygoogleaccount - 123456
Facebook: myfacebookaccount - 654321
Twitter: mytwitteraccount - 098765

Use Case 6: Rename an Account

Code:

ykman oath accounts rename mygoogleaccount Google:my_updated_google_account

Motivation:

Renaming an account is beneficial when there is a need to update the descriptor or when following a new naming convention. This helps in maintaining uniformity and clarity across different accounts, especially when numerous accounts are stored.

Explanation:

• ykman: Calls the YubiKey Manager command-line interface.
• oath: Points to the Open AuTHentication toolset.
• accounts: Concerns account administration.
• rename: Alter the existing name of an account.
• mygoogleaccount: The current identifier to be renamed.
• Google:my_updated_google_account: The new name, including an optional issuer, desired for the account.

Example Output:

Account Google:mygoogleaccount renamed to Google:my_updated_google_account.

Use Case 7: Delete an Account

Code:

ykman oath accounts delete mytwitteraccount

Motivation:

Deleting an account is necessary when a user decides to decommission an authentication setup, possibly due to an account closure, a security incident, or simply reducing clutter on their YubiKey device.

Explanation:

• ykman: Commands the YubiKey Manager utility.
• oath: Targets operations on the OATH service.
• accounts: Involves management tasks for accounts.
• delete: Specifies the removal of a specific account.
• mytwitteraccount: The account name or keyword identifying which account is to be purged.

Example Output:

Account Twitter:mytwitteraccount deleted successfully.

Use Case 8: Delete All Accounts and Restore Factory Settings

Code:

ykman oath reset

Motivation:

Resetting the OATH application to factory settings is often utilized in scenarios where a complete overhaul is required, such as passing the YubiKey to another user, resolving persistent issues, or removing all current accounts for a fresh setup.

Explanation:

• ykman: Calls the operation with YubiKey Manager.
• oath: Indicates that this action applies to the OATH application.
• reset: Commands a comprehensive removal of all stored accounts, reverting the application to its original factory state.

Example Output:

All accounts deleted. OATH application reset to factory settings.

Conclusion:

The ‘ykman oath’ command is an invaluable tool for managing OATH configurations on your YubiKey. By understanding its various applications, from simply listing accounts to complex tasks like resetting configurations, users can effectively maintain their authentication setups and enhance the security of their digital identities.