How to use the command 'ykman oath' (with examples)

The ‘ykman oath’ command is used to manage the OATH (Initiative for Open Authentication) YubiKey application. This application allows users to store and generate one-time passwords (OTP) and two-factor authentication (2FA) codes on their YubiKey device. With the ‘ykman oath’ command, users can perform various operations such as adding new accounts, renaming accounts, deleting accounts, and more.

Use case 1: Display general information about the OATH application

Code:

ykman oath info

Motivation: This use case is useful when you want to get a quick overview of the OATH application on your YubiKey. It provides information about the number of accounts stored, the supported algorithms, the touch policy, and other relevant details.

Explanation:

• ykman oath info: This command displays general information about the OATH application.

Example output:

Name: OATH
Version: 1.1.0
Number of accounts: 5
Algorithms: ['SHA1', 'SHA256', 'SHA512']
Touch policy: Cached

Use case 2: Change the password used to protect OATH accounts

Code:

ykman oath access change

Motivation: If you have set a password to protect your OATH accounts on the YubiKey, and you want to change it, this use case is helpful. Changing the password regularly enhances the security of your accounts.

Explanation:

• ykman oath access change: This command is used to change the password used to protect the OATH accounts stored on the YubiKey. Adding the --clear option will remove the existing password.

Example output:

Please enter your current password:
Please enter your new password:
Please confirm your new password:
Password changed successfully.

Use case 3: Add a new account

Code:

ykman oath accounts add --issuer "issuer name"

Motivation: When you want to add a new account to the OATH application on your YubiKey, you can use this use case. It allows you to specify the issuer name for easier identification of the account.

Explanation:

• ykman oath accounts add --issuer "issuer name": This command adds a new account to the OATH application with the specified issuer name.

Example output:

Please enter the account name:
Please enter the secret key:
New account added successfully.

Use case 4: List all accounts (with their issuers)

Code:

ykman oath accounts list

Motivation: Sometimes, you may want to view a list of all the OATH accounts stored on your YubiKey. This use case provides that functionality, along with the respective issuers for each account.

Explanation:

• ykman oath accounts list: This command lists all the accounts stored in the OATH application, along with their issuers.

Example output:

Accounts:
- Issuer: Google
  Name: john.doe@gmail.com
- Issuer: Microsoft
  Name: john.doe@hotmail.com
- Issuer: GitHub
  Name: john.doe

Use case 5: List all accounts with their current TOTP/HOTP codes

Code:

ykman oath accounts code keyword

Motivation: This use case is useful when you need to retrieve the current Time-based One-Time Password (TOTP) or HMAC-based One-Time Password (HOTP) codes for all the accounts stored on your YubiKey. You can also filter the list by providing a keyword, making it easier to find specific accounts.

Explanation:

• ykman oath accounts code keyword: This command lists all the accounts stored in the OATH application, along with their current TOTP/HOTP codes. You can filter the list by providing a keyword.

Example output:

Accounts:
- Issuer: Google
  Name: john.doe@gmail.com
  Code: 123456
- Issuer: Microsoft
  Name: john.doe@hotmail.com
  Code: 654321
- Issuer: GitHub
  Name: john.doe
  Code: 987654

Use case 6: Rename an account

Code:

ykman oath accounts rename keyword issuer:name|name

Motivation: If you need to change the name of an existing account stored on your YubiKey, this use case can be valuable. It allows you to easily rename the account, making it more recognizable or descriptive.

Explanation:

• ykman oath accounts rename keyword issuer:name|name: This command renames an account specified by the keyword. You can provide either the issuer name and current account name or just the current account name.

Example output:

Please enter the new name for the account:
Account renamed successfully.

Use case 7: Delete an account

Code:

ykman oath accounts delete keyword

Motivation: When you no longer need a specific OATH account stored on your YubiKey, you can delete it using this use case. Deleting unnecessary accounts helps maintain a clean and manageable account list.

Explanation:

• ykman oath accounts delete keyword: This command deletes the account specified by the keyword.

Example output:

Account deleted successfully.

Use case 8: Delete all accounts and restore factory settings

Code:

ykman oath reset

Motivation: If you want to remove all the accounts stored on your YubiKey and restore the factory settings of the OATH application, this use case is helpful. It provides a simple way to reset the application to its initial state.

Explanation:

• ykman oath reset: This command deletes all the accounts stored in the OATH application and restores the factory settings.

Example output:

All accounts deleted.
Reset completed successfully.

Conclusion:

The ‘ykman oath’ command is a powerful tool for managing the OATH YubiKey application. With the various use cases covered in this article, you can now effectively add, rename, delete accounts, change passwords, and perform other relevant operations on your YubiKey. Remember to refer to the Yubico documentation for more details on the different commands and their options.