Setting PIN Unblock Code (PUK)

When a YubiKey is used with the YubiKey Smart Card Minidriver (YubiKey Minidriver) for the first time, the YubiKey Minidriver checks to ensure that the Management Key and the PIN Unblock Code (PUK) have been changed from the default values.

If they have not been changed from the default value, the YubiKey Minidriver upgrades the Management Key to a protected non-default value and blocks the PUK so that the PIN remains blocked. A blocked PUK prevents the PIN Unblock function from being active.

Set or Change Smart Card PIN

The steps in this section use the YubiKey Manager (GUI) to enable:

• Setting the smart card PIN during enrollment through the Windows interface.
• Changing the PIN directly through the Windows interface.

1. To prevent the PUK from being blocked, configure the local registry prior to setting up YubiKeys.

   Key

   HKLM\\Software\\Yubico\\ykmd

   Value

   BlockPUKOnMGMUpgrade (DWORD) - 0 turns off the PUK block feature, any other value enables it.

2. The YubiKey Minidriver supports unlocking a blocked PIN using the built-in Windows UI. To enable this function, 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

3. For the PUK to remain unblocked, use either the YubiKey Manager, the Yubico PIV Tool, or Yubico Authenticator to set a non-default PUK prior to using the Windows interface to load or access certificates stored on the YubiKey.

   When the YubiKey Minidriver first accesses the YubiKey, it checks if the PUK is set to the default value. For PUKs with user supplied values, this causes 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.

4. Setting the PUK can be accomplished in YubiKey Manager by navigating to:

   Applications > PIV > Configure PINs > Change PUK

To use the command-line version of YubiKey Manager (ykman), see the YubiKey Manager (ykman) CLI and GUI Guide, section ykman piv access change-puk.

To manage the FIDO2 PIN, see the Yubico Authenticator User Guide, section PIN Protection.

To use Yubico PIV tool, refer to the documentation on Yubico PIV Tool.

Unblock a Blocked PIN

When a user enters their PIN incorrectly three times consecutively, the PIN is blocked and the smart card features are unusable until the PIN is unblocked.

If a PIN Unlock Key (PUK) was created for the device, the YubiKey Minidriver allows the PIN to be unblocked directly in the Windows interface by providing the PIN Unlock Key (PUK), in hexadecimal format.

Important

You cannot create a PUK with the YubiKey Minidriver.

To create a PUK for a YubiKey, follow the instructions for Setting PIN Unblock Code (PUK) using either the YubiKey Manager, the Yubico PIV Tool, or Yubico Authenticator.

If you do not create a PUK and you forget your PIN, recovery requires that you reset the device. Resetting the device:

• Permanently deletes all private keys and certificates.
• Requires new certificates and private keys!

By default, the user PIN is blocked when three consecutive incorrect PINs have been entered. The PIN Unblock Code (PUK) is used for unblocking the user PIN. To use the PUK, the administrator must have the PUK enabled when the key and certificate were loaded on the YubiKey. If both the PIN and the PUK are blocked, the YubiKey must be reset, which deletes any loaded certificates and returns the PIN and PUK to default values (123456 and 12345678, respectively).

Note

Both Windows Server 2008 and Windows Server 2008 R2 require the PIN unblock code (PUK) to be typed in as hexidecimal digits. This means that if your PUK is 12345678, to unlock a pin through the Windows UI, you must type the ASCII hex-encoded bytes of the PUK string (in this case, the unlock code would be 3132333435363738). Refer to an ASCII chart (for example, www.asciitable.com) to encode a PUK in hexidecimal. This does not apply to later versions of Windows.

To unblock the user PIN:

1. With the YubiKey inserted, attempt to log in at the Windows login screen. When the PIN is blocked, the following screen appears (example in Windows 10).

   

2. Check the checkbox next to Unblock smart card.

   

3. In the Response field, enter the PUK code in hexadecimal format. For example: the default value of 12345678 in hexadecimal format is 3132333435363738.

4. In the New PIN and Confirm PIN fields, enter a new, properly formatted PIN, and then press Enter.

5. Remove the YubiKey, reinsert, and test the new PIN to confirm you can access the account.

   Note

   To enable this function, set the Allow Integrated Unblock screen to be displayed at the time of logon Group Policy Object. This setting is located in:

   Computer Configuration > Administrative Templates > Windows Components > Smart Card