Deploying the YubiKey Smart Card Minidriver to workstations and servers

YubiKey Smart Card Minidriver installation

The YubiKey Smart Card 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 Smart Card Minidriver is available to be downloaded directly from the Yubico website here. 

When installing the YubiKey Smart Card 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 Smart Card Minidriver can be downloaded directly from the Yubico website and be distributed and installed manually by anyone with administrator rights on the computer. The YubiKey Smart Card Minidriver 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 Smart Card Minidriver.

1. Download the YubiKey Smart Card Minidriver, available here as an 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-[version].MSI and 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 Smart Card 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 Smart Card Minidriver prior to installing the latest version via the CAB file (using the MSI installer does this automatically).

1. Download the YubiKey Smart Card Minidriver, available here.

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-[version].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.

 Tip: Earlier versions of the YubiKey Smart Card Minidriver will not be automatically removed when installing via the CAB file, so the MSI installer should be used wherever possible.

Command line install

The YubiKey Smart Card 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.6.3.252-x64.msi

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

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

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

Installing the MSI with the Legacy Node option enabled on servers will prevent smart card login over RDP failing with error "The requested key container does not exist on the smart card." See this article for reference.

Installing via Group Policy Object

For large deployments, the YubiKey Smart Card 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 Smart Card 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 Smart Card Minidriver for the first time, the YubiKey Smart Card Minidriver checks to ensure default values are not being used for the Management Key (MGM) and the PIN Unblock Code (PUK). If the default values are in use, the YubiKey Smart Card 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 PUK must be changed to a non-default value (e.g. any 6-7 digit value that isn't 12345678) prior to verifying the PIN for the first time using the YubiKey Smart Card Minidriver.

The YubiKey Smart Card 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 YubiKey Smart Card 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 Yubico Authenticator by navigating to Certificates > Change PUK.

For using the command-line version of YubiKey Manager (ykman), see this document.

For using Yubico PIV tool, refer to the documentation here.

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 Smart Card 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 YubiKey Smart Card 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 YubiKey Smart Card 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.

 Warning: 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 must adhere to has no concept of touch requirement as it was designed for standard card form factor smart cards such as the Common Access Card). User education and user experience must be strongly considered when making this decision.

Logging YubiKey Smart Card Minidriver behavior

Should errors occur in the use of the YubiKey with the YubiKey Smart Card 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