TABLE OF CONTENTS
Working with the YubiKey and the YubiKey Minidriver, there are a number of options to help troubleshoot issues with the YubiKey. As Yubico receives more feedback from customers, this section will be updated with common questions and fixes.
YubiKey Smart Card Specifications
There are storage limitations to consider when loading multiple certificates to the YubiKey:
YubiKey 4 & 5
The YubiKey 4 & 5 has a maximum certificate size of 3052 bytes in DER format. Up to twelve (12) certificates can be stored concurrently.
The YubiKey 4 & 5 has 15,260 bytes available for storing Certificate Chain Certificates (root and intermediate certificates).
The firmware doesn't report how much space allocated to the smart card applet is currently in use.
The YubiKey NEO has a maximum certificate size of 2024 bytes in DER format. Up to four (4) certificates can be stored concurrently.
The YubiKey NEO has 10120 bytes available for storing Certificate Chain Certificates (root and intermediate certificates).
Since the YubiKey Minidriver prioritizes assigning slots for keys by smart card usage, it will place the first two authentication keys in slots 9a and 9d during enrollment. This driver is designed for the YubiKey 4 & 5 which has additional retired slots available for general purpose (82-90), so it will attempt to place a third exchange key in slot 82. For details, refer to https://developers.yubico.com/PIV/Introduction/Certificate_slots.html.
Some YubiKey 4 devices were part of the Infineon RSA key generation vulnerability, CVE-2017-15361, referred to by its discoverers as “Return of Coppersmith’s Attack” (ROCA). This vulnerability concerns the generation of weak keys that may allow the private key to be derived by an attacker in possession of public key.
To protect against this vulnerability, features have been included in the YubiKey Minidriver to alert users and administrators to potentially vulnerable devices and allow for the option to prevent weak RSA keys from being generated on those YubiKey 4s. YubiKeys not affected by the ROCA vulnerability (YubiKey NEOs and some YubiKey 4 devices) will retain all key generation functionality without change.
For more information on ROCA, Yubico’s response and options for addressing these vunerabilties, as well how to identify YubiKeys affected by the vunerability, See Yubico Security Advisory YSA-2017-01 https://www.yubico.com/support/security-advisories/ysa-2017-01.
By default, the YubiKey Minidriver will allow RSA key generation on vulnerable YubiKey 4 hardware, but will create a warning in the Windows Log for all successful RSA key generation events. The log message will include the serial number of the YubiKey 4, indicate the YubiKey needs to be replaced, and refers to the YSA-2017-01 security advisory for additional information. An Error is logged for all failed RSA key generation events on vulnerable YubiKey 4 that were blocked based on a user or admin configuration option.
Local or end users, without Windows admin privileges, can set a Windows environment variable to either block or allow RSA key generation on YubiKey 4 devices affected by ROCA via the YubiKey Minidriver.
Block RSA keygen: YUBIKEY_PIV_ENABLE_UNSAFE_KEYGEN_ROCA=0
Allow RSA keygen: YUBIKEY_PIV_ENABLE_UNSAFE_KEYGEN_ROCA=1
Windows administrators can set a Windows registry entry to either block or allow RSA key generation on YubiKey 4 devices affected by ROCA. This key admin setting overrides the user configuration option, if the user config is set. These entries can be pushed out via group policy.
Block RSA keygen: HKLM\Software\Yubico\yubikeypiv\Enable_Unsafe_Keygen_ROCA=0
Allow RSA keygen: HKLM\Software\Yubico\yubikeypiv\Enable_Unsafe_Keygen_ROCA=1
Should the YubiKey Minidriver be uninstalled, these settings, both local and registry, will persist and be applied if the Minidriver is re-installed.
If I YubiKey is connected to a computer when installing the YubiKey Minidriver, Windows may continue to use the native generic smart card minidriver. The YubiKey Minidriver can be set as the default driver by following these steps:
Connect your YubiKey to your computer.
Open up Device Manager.
Locate the YubiKey smart card entry - it will be labeled Identity Device (NIST SP 800-73 [PIV]). Right click the entry and select Update driver.
In the window which opens, select Search automatically for updated driver software.
A list of drivers will be displayed. Select YubiKey Minidriver.
The YubiKey NEO, when trying to enroll a certificate larger than the supported maximum key size of 2048 bits may freeze unexpectedly. For larger certificates, it is recommended to use the YubiKey 4 or 5 hardware.
When attempting to import a certificate into the YubiKey 4 or 5 when the card has reached its maximum storage of 12 certificates, the certutil program may show an inconsistent number of certificates.
Due to a limitation with the legacy CSP, the Microsoft Base Smart Card Crypto Provider will not see any ECC certificates or keys. To view ECC certificate and key information, use the Smart Card Key Storage Provider:
We recommend you use the "Microsoft Smart Card Key Storage Provider" for better security and functionality.
The Microsoft Smart Card Key Storage Provider does not support importing ECC keys and certificates through the certutil program. This is a limitation of the certutil program.
Windows 7 may not be able to verify code integrity of the YubiKey Minidriver DLL (ykmd.dll) due to the SHA256 signature of Yubico’s code signing certificate. If you see a "Bad Image" warning when running certutil or see error 3002 in the Microsoft Windows CodeIntegrity Operational log, apply update KB3033929 to resolve this issue.
When the YubiKey is not seen as a smart card on the host Window PC, Administrators can try the following troubleshooting steps to resolve the issue.
Details and Configuration
If working with a YubiKey with existing keys, the minidriver will automatically create containers for slots containing RSA and ECC keys with corresponding valid certificates if the keys/certs have been manually through other tools.
PIN and touch policy are set when a key is imported or generated and cannot be changed after it is configured on the device. By default, the PIN and touch policy for imported/generated keys through the minidriver are created using the default settings according to YKPIV_PINPOLICY_ONCE (1) and YKPIV_TOUCHPOLICY_DEFAULT (0). The PIN policy cannot be modified. To alter the touch policy behavior, the following registry entry must be configured prior to setting up keys. Note, changing these settings is most commonly done using an enrollment machine where multiple YubiKeys will be configured.
Value: NewKeyTouchPolicy (DWORD) - sets the touch policy on new keys generated/imported through the minidriver. Accepted values are the numeric value of the touch policy definition from ykpiv.h
Blocked PUK: The Minidriver will automatically block a PUK using the default value (12345678) the first time the PIN is entered via the Minidriver. The Minidriver checks if the default value is in use by attempting a PUK Reset using the default value for the PUK. If the PUK has been set to a value other then the default, this will cause a failed attempt to decrement the PUK retry counters by one. If the PUK retry counter is set to 1, this will lock the PUK. Yubico recommends leaving the PUK retry attempts at or above the default value of 3. A successful PIN Reset using the PUK via the Minidriver or PIV Tool will reset the current PUK retry counter.
For issues not resolved by this guide, it is recommended to enter a support ticket at https://www.yubico.com/support/get-support/ . To assist in the diagnostics of issues, it is recommended to include a log file containing the issue observed.
To enable the debug log file, add the following registry key and log files will be created per running process in C:\Logs.
Value: DebugOn (DWORD) - to enable logging set value to 1.
Uninstalling the YubiKey Minidriver
Should you determine that you prefer to utilize the inbox generic class minidriver provided by Microsoft (msclmd.inf) to access the YubiKey PIV functions instead of the YubiKey Minidriver. If the Yubico Mindriver was installed using the MSI, Yubico recommends using the Program and Features Interface to remove it.
Use Windows+R to display the Run window, type inand click OK.
The Programs and Features window will open. Scroll down and locate the entry for the YubiKey Smart Card Minidriver.
Right click on the Yubico Minidriver entry and select Uninstall.
Should this not be an option or if you choose to manually uninstall, follow the instructions below to uninstall the YubiKey Minidriver.
Open Command Prompt as Administrator or PowerShell as Admin.
Type cdand press Tab, and then press Enter. The current path should look similar to the following:
If multiple versions of the YubiKey Minidriver have been installed, each will have a separate directory. Repeat this and the following steps for each one.
Type the following command and press Enter:
If you want to also delete the driver and other related files from your computer, delete the entire YubiKey Minidriver directory in(using the example in step 3, the directory name is ykmd.inf_amd64_1e4c7d5bdb6914f9). To do so, the Admin will need to take ownership of the directory using the command. For example, use the directory from step 3, the command would be:
Following taking ownership of the directory, grant full control access to the directory and the files within with the
Once the ownership and access is set, the files can be deleted as normal.
Preventing Reinstallation after Removal
To prevent the YubiKey Minidriver from being reinstalled after removal, it can be blocked via the Windows Group Policy.
Right-click the Windows Start button and select Run.
Typeand press Enter.
Navigate to the AD forest and Domain containing your server, double-click your server and double-click Group Policy Objects.
Right-click on the group policy you want to edit, and then select Edit.
Expand Computer Configuration -> Administrative Templates -> System -> Device Installation -> Device Installation Restrictions.
Right-click Prevent installation of the of devices that match any of these device IDs and select Edit.
Click the option Enabled.
Under Options, click Show.
Enter the Hardware ID. This can be found via Device Manager:
Click on Smart Cards -> YubiKey Smart Card
Right click on the YubiKey Smart Card and select Properties.
Open the Details tab, and the Drop down to Hardware ids
Thevalue for the YubiKey will be displayed. Note the YubiKey 4/5 and YubiKey NEO have different hardware IDs.