Deploying the YubiKey Minidriver to Workstations and Servers

YubiKey Minidriver Installation

The Minidriver must be installed on all machines where the YubiKey will be used as a smart card to access. These include servers which users remotely connect to, as well as the connecting PC. The YubiKey Minidriver is available to be downloaded directly from the Yubico website at https://www.yubico.com/products/services-software/download/smart-card-drivers-tools/.

When installing the YubiKey Minidriver, users have the option of using an MSI installer via the Windows GUI or Command line, and a CAB file. It is recommended to use the MSI Installer for local installations, the MSI Installer via command line for remote computers and Servers, and the CAB file for large Enterprise deployments in conjunction with a Group Policy Object Endpoint Configuration utility.

Manual Install

The YubiKey Minidriver can be downloaded directly from the Yubico website and be distributed and installed manually by anyone with administrator rights on the computer. The Minidriver software is available as both an MSI installer for 32 and 64 bit systems, as well as a CAB file.

MSI File install

The MSI Installer is the preferred method of manually installing the YubiKey Minidriver.

1. Download the YubiKey Minidriver, available at https://www.yubico.com/products/services-software/download/smart-card-drivers-tools/ as a MSI file. Select the 32 or 64 bit installer as appropriate for the environment it will be installed on.

2. Locate and double-click on YubiKey-Minidriver MSI Windows Installer.

3. Follow the prompts to install the driver. If prompted, restart your computer.

Note that the MSI installer will automatically look for, and uninstall, previously installed YubiKey Smart Card driver versions from both CAB, Windows Update, and an earlier Windows installer package.

CAB File install

Installing the YubiKey Minidriver via CAB file is suggested in cases where installing via the MSI installer is prohibited. It is recommended to remove previous version of the Yubico Minidriver prior to installing the latest version via the CAB file.

1. Download the YubiKey Minidriver, available at https://www.yubico.com/products/services-software/download/smart-card-drivers-tools/ as a CAB file.

2. Extract the downloaded CAB file to your preferred location. This can simply be done via the command line interface using the Expand command. For example, to extract the contents to the C:\ykmd directory, use the command:
   expand.exe yubikey-minidriver-4.1.1.210.cab -F:* C:\ykmd 

3. Ensure no YubiKey is currently connected to your computer.

4. Locate and right-click on ykmd.inf and select Install.

5. Follow the prompts to install the driver. If prompted, restart your computer.

Note that earlier versions of the minidriver will not be automatically removed when installing via the CAB file.

Command Line Install

The YubiKey Minidriver MSI can also be installed via command line using the msiexec command. The basic command line install command is:

msiexec /i YubiKey-Minidriver-4.1.1.210-x64.msi

msiexec /i YubiKey-Minidriver-4.1.1.210-x64.msi /passive

msiexec /i YubiKey-Minidriver-4.1.1.210-x64.msi /quiet

msiexec /i YubiKey-Minidriver-4.1.1.210-x64.msi INSTALL_LEGACY_NODE=1 /quiet

Installing the MSI with the Legacy Node option enabled on servers will prevent the Smart Card Logon Over RDP Fails with "Requested Key Container is not Available" error.

Installing via Group Policy Object

For large deployments, the YubiKey Minidriver can be centrally installed via Group Policy Objects. By leveraging a powershell script for the necessary commands and a shared network drive accessible from every client station to distribute the YubiKey Minidriver files, an Administrator can automate the installation. When creating an installation script, an Administrator will need to ensure they define registry entries for the PUK Policy, the Touch Policy and the Debug Log Policy, as well as installing the INF file directly.

Installation verification

Following is a PowerShell script that can be used to verify proper installation of the YubiKey Smart Card Minidriver. This script needs to be run in a PowerShell window with elevated permissions:

Get-WindowsDriver -Online | where {($_.ProviderName -like "Yubico") -and ($_.ClassName -like "SmartCard") -and ($_.Version -like "*")} | select ProviderName,ClassName,Version

Setting PIN Unblock Code (PUK)

When a YubiKey is used with the YubiKey Minidriver for the first time, the YubiKey Minidriver checks to ensure default values are not being used for the management key and the PIN Unblock Code (PUK). If the default values are in use, the YubiKey Minidriver will upgrade the Management key to a protected value and block the PUK. A blocked PUK will prevent the PIN Unblock function from being active.

To prevent the PUK from being blocked, the local registry must be configured prior to setting up keys.

• Key:  HKLM\Software\Yubico\ykmd
• Value: BlockPUKOnMGMUpgrade (DWORD) - 0 turns off the PUK block feature, any other value enables it

The YubiKey Minidriver supports unlocking a blocked PIN using the built-in Windows UI.  To enable this function, you need to enable the Allow Integrated Unblock screen to be displayed at the time of logon in Windows Group Policy.  This configuration setting is located in:  Computer Configuration->Administrative Templates->Windows Components->Smart Card

For the PUK to remain unblocked, YubiKey Manager or the Yubico PIV Tool must be used to set a non-default PUK prior to using the Windows interface to load or access certificates stored on the YubiKey. When the Minidriver first accesses the YubiKey, it will check if the PUK is set to the default value - for PUKs with user supplied values, this will cause the retry counter to decrement by one. This can be reset by entering the correct PUK via the Windows interface, but requires changing the PIV PIN.

Setting the PUK can be accomplished in YubiKey Manager by navigating to Applications > PIV > Configure PINs > Change PUK.

For using the command-line version of YubiKey Manager (ykman), see the section ykman piv change-puk on https://support.yubico.com/support/solutions/articles/15000012643-yubikey-manager-cli-ykman-user-manual.

For using Yubico PIV tool, refer to the documentation on https://developers.yubico.com/yubico-piv-tool/.

Setting Touch Policy

The YubiKey can be set to require a physical touch to confirm any cryptographic operations. This is an optional feature to increase security, ensuring that any authentication operation must be carried out in person. The YubiKey Minidriver sets the touch policy when a key is first imported or generated. Once set for a key on the YubiKey, the policies cannot be changed.

By default, the touch policy for keys imported/generated through the minidriver is created with the default setting of the touch policy disabled.

To alter the policy behavior, the registry must be configured prior to setting up keys, either on the station enrolling the keys or pushed out to all machines using Group Policy Objects.

• Key: HKLM\Software\Yubico\ykmd
• Value: NewKeyTouchPolicy (DWORD) - sets the touch policy on new keys generated/imported through the minidriver.  Accepted values are
  • 1 <Never> - Default policy of never requiring a user touch.
  • 2 <Always> - Policy is set to require a user touch to confirm each and every cryptographic operation. Yubico does not recommend using this setting, as some Windows services, such as login, may require multiple cryptographic operations in a short time span.
  • 3 <Cached> - Policy is set to require physical touch once, then allow for cryptographic operations in a small time window afterwards. For using the physical touch option with Windows Smart Card Logon, this option is required.

Note: Due to OS limitations, there is no visual prompt on the screen when touch is required in this scenario (Microsoft's minidriver specification that ykmd is based off of has no concept of touch requirement).

Logging Minidriver Behavior

Should errors occur in the use of the YubiKey as a PIV Smart Card with the YubiKey Minidriver, error logging can be enabled on the local computer using the registry. Once enabled, log files will be created per running process in C:\Logs. See here for additional troubleshooting steps.

• Key: HKLM\Software\Yubico\ykmd
• Value: DebugOn (DWORD) - 1 enables error logging.

Next: YubiKey PIN and PUK User Management on Windows