As mentioned in previous articles, Yubico has developed various tools to customize the vast range of functions YubiKey offers. This article will introduce these tools from a developer's standpoint.
Table of Contents for this Series
・Tools for Developers (this article)
Contents of this Article
YubiKey Manager
YubiKey Personalization Tool
YubiKey PIV Manager
Yubico Authenticator
CLI Tool Writers
Additional Information
Review
The previous articles introduced the two major types of YubiKeys - Security Key by Yubico and the YubiKey 5 series.
Security Key by Yubico supports only the FIDO protocol; therefore, only the YubiKey Manager tool is available.
YubiKey Manager
YubiKey Manager's Startup Screen
YubiKey Manager is a Python tool to configure various settings for YubiKey.
Configure Security Key by Yubico
By inserting the Security Key by Yubico (the one with the "2" stamped), one can set the PIN and reset the key from the Applications tab.
Set up Security Key by Yubico in YubiKey Manager
However, if the key is reset, all credentials registered thus far will be deleted.
※ If an older product that can only be used with U2F is inserted, no settings will be able to be made.
Cannot be Used with Older Products that Only Support U2F
Configure YubiKey 5 settings
When YubiKey 5 is inserted, in addition to the above settings related to the FIDO protocol, Interface settings and settings for each slot can also be configured.
Inserting YubiKey 5C Nano
Interface Settings
The Interface setting determines which functions of YubiKey are enabled. For example, one may want to use YubiKey 5's FIDO and PIV functions, but not OTP, so they may want to temporarily disable it.
Interface Settings
Also, these settings can be easily enabled or disabled so users can change them as needed.
Slot Settings
Slot setting switches the OTP function of YubiKey. This setting can be used while registering OTPs with unique secrets to a service such as okta, such as while setting up an OTP authentication server or an OATH-HOTP other than Yubico OTP.
OTP Slot 1, 2 Settings
This article will not thoroughly explain this tool as it is not used in everyday practice.
YubiKey Personalization Tool
YubiKey Personalization Tool is a tool that allows one to configure the YubiKey Manager's slot settings more precisely.
YubiKey Personalization Tool's Startup Screen
This tool allows the configuration of detailed settings related to YubiKey's OTP output.
Specifically, as with YubiKey Manager, one can configure Yubico OTP/OATH-HOTP/Static Password/Challenge-Response, etc., for two slots (Slot1 and 2) of YubiKey. In addition, there are also options to
Set YubiKey Neo's NDEF function.
Configure tap behavior on metal parts.
Insert tab and Enter key before and after OTP input.
Configure YubiKey's LEDs.
and so on.
YubiKey Personalization Tool Option Settings Screen
Another significant difference in the YubiKey Manager is the ability to configure multiple YubiKeys in sequence, which is useful for integrations where OTP must be configured for many YubiKeys.
YubiKey PIV Manager
PIV Manager is used for setting up the PIN, PUK, and Management Key, importing certificates, creating self-issued certificates, and requesting certificates to be issued to CSRs for the YubiKey.
PIV Manager Startup Screen
This tool is safe to use in Linux and Mac environments. Still, please be careful while using it via Windows CNG in a Windows environment, as by changing the Management Key in this tool, one will not be able to write certificates via CNG.
Yubico Authenticator
Yubico Authenticator (Android Version)
Yubico Authenticator is an application that can register and display TOTP, similar to Google Authenticator. The TOTP seed (secret information that generates the OTP) is usually stored in the device that displays the TOTP, but with the Yubico Authenticator application, the seed is stored in the YubiKey, allowing the TOTP to be displayed on multiple devices.
Yubico Authenticator(Windows Version)
CLI Tools
Previously GUI tools were introduced, but now, this article will introduce CLI tools instead.
These CLI tools were previously required to be introduced one by one. However, they can now be integrated directly into the YubiKey Manager, and more developments are actively being made.
How to Install
On Windows, pass through the bundled YubiKey Manager GUI; on Mac, use "brew install ykman" or "pip install ykman" via pip to install.
How to use
The ykman command can be used to automate integration and change parameters that the GUI tools cannot change.
For example, one can efficiently change the mode and
# FIDO + CCID Mode Change
$ ykman mode -f f+cParameters that cannot be changed in the GUI, such as changing the number of PIN and PUK attempts in PIV mode, can also be changed.
# PIN (Change Number of Trials)
$ ykman ykman piv set-pin-retries -P 123456 10 5
WARNING: This will reset the PIN and PUK to the factory defaults!
Set PIN and PUK retry counters to: 10 5? [y/N]: y
Default PINs are set.For more information, please read the 、YubiKey Manager CLI (ykman) User Manual : Yubico Support.
Additional Information
Here, scoop is used to install YubiKey tools in the Windows environment. However, users can also download the basic set of tools from here in one shot.
# adding extra buckets
$ scoop bucket add extras
# YubiKey search for related tools
$ scoop search yubi
'main' bucket:
yubico-piv-tool (1.6.2)
yubikey-personalization (1.19.0)
'extras' bucket:
yubikey-manager-qt (0.5.2)
yubikey-personalization-gui (3.1.25)
yubikey-piv-manager (1.4.2)
# yubikey manager qt installation
$ scoop install yubikey-manager-qt
# ykman.exe passing the path
$ ykman --help
Usage: ykman.exe [OPTIONS] COMMAND [ARGS]...
Configure your YubiKey via the command line.
Options:
-v, --version
-d, --device SERIAL
-l, --log-level [DEBUG|INFO|WARNING|ERROR|CRITICAL]
Enable logging at given verbosity level
--log-file FILE Write logs to the given FILE instead of standard error; ignored unless
--log-level is also set
-h, --help Show this message and exit.
Commands:
config Enable/Disable applications.
fido Manage FIDO applications.
info Show general information.
list List connected YubiKeys.
mode Manage connection modes (USB Interfaces).
oath Manage OATH application.
openpgp Manage OpenPGP application.
otp Manage OTP Application.
piv Manage PIV application.Conclusions
This article introduced various tools to write or change YubiKey credentials. However, as overwriting YubiKey credentials may erase the current ones and make them impossible to restore, please do so cautiously.
Please contact us through the Contact page for more information or support regarding YubiKey.