.. md_config-registry.rst .. _md-config-registry-label: ================================= Configure the Minidriver Registry ================================= The YubiKey Smart Card Minidriver can be configured for non-default behavior through the registry keys. To configure the YubiKey Minidriver registry entries: 1. As administrator, open the Registry Editor. 2. Create the key: ``HKEY_LOCAL_MACHINE\SOFTWARE\Yubico\ykmd``. 3. Refer to the table below to add key value(s) as applicable. 4. Close the registry editor and reboot the machine. YubiKey Minidriver Registry Key Reference ========================================== .. Important:: Always thoroughly test configuration prior to implementation. Furthermore, to mitigate risks, we recommend that all testing be conducted in a controlled test environment. Finally, note that unless you use the latest version, not all of the settings are necessarily available in your YubiKey Minidriver. You should therefore use the latest version. .. table:: :widths: 20 10 10 60 :class: longtable +------------------+-------+--------+----------------------------------------------------------------------------+ | Value | Type | Data | Description | +==================+=======+========+============================================================================+ | AutoFingerprint | DWORD | 1 (0) || Controls the biometric authentication dialog for the YubiKey Bio | | | | || Multi-protocol Edition. Default ``1``. The YubiKey Minidriver | | | | || immediately asks for fingerprint verification if a fingerprint | | | | || is enrolled on the device AND is not blocked. | +------------------+-------+--------+----------------------------------------------------------------------------+ || BlockPUKOnMGM | DWORD | 0 (1) || Controls availability of PUK when the YubiKey is configured with | || Upgrade | | || known values. Default ``1``. The YubiKey Minidriver restricts PUK | || | | || access when the YubiKey value, is at factory value, ``12345678``. | || | | || Set to ``0``, the PUK functionality is not restricted, regardless | || | | || if the YubiKey factory value is unchanged. | || | | || Note: Allowing unblock (PUK) with a known factory value can be | || | | || a concern. | +------------------+-------+--------+----------------------------------------------------------------------------+ | DebugOn | DWORD | 0 (1) || (Optional) Activates creating a debug log. | | | | || To enable, set value to ``1``. The registry key value triggers | | | | || generating a debug log major security that is saved to: ``C:\Logs`` | +------------------+-------+--------+----------------------------------------------------------------------------+ | DebugVerbosity | DWORD | 0 (1-3)|| Applies only when DebugOn is non-zero. Sets logging level used | | | | || by the YubiKey Minidriver and its dependencies. Valid values are | | | | || (0) - none to (3) - APDU level verbosity. | +------------------+-------+--------+----------------------------------------------------------------------------+ | ExternalPinCache | DWORD | 2 (1-4)|| This setting overrides the `PIN_CACHE_POLICY_TYPE`` for the | | Policy | | || external PIN_ID in the YubiKey Minidriver. This setting controls | | | | || how the YUbiKey Bio PIN (fingerprint) is cached. | | | | || Default is 0 (PinCacheNormal). This key accepts any valid | | | | || ``PIN_CACHE_POLICY_TYPE`` numeric value. | | | | || See https://learn.microsoft.com/en-us/windows-hardware/drivers/smartcard/ | | | | || card-pin-operations#-pin_cache_policy_type for more information. | +------------------+-------+--------+----------------------------------------------------------------------------+ | ManageCSPCache | DWORD | 1 (0) || Determines if by clearing its cached data, the container map | | | | || synchronization check compels the BaseCSP to retrieve the | | | | || container map and certificate details from the YubiKey Minidriver. | | | | || When disabled, ``0``, this feature prevents certain card modifications | | | | || from being reflected in the BaseCSP. | | | | || Note: Deactivating, ``0``, this feature can enhance the certificate | | | | || enumeration performance. | +------------------+-------+--------+----------------------------------------------------------------------------+ | NewKeyTouch | DWORD | 1 (2,3)|| Enables the touch policy for PIV. Setting is optional. | | Policy | | || Default ``1``, touch input is not mandatory for PIV operations. | | | | || Set to ``2``, touch input is enforced at all times (similar to FIDO2). | | | | || Set to ``3``, touch input activated, with cache touch input for a | | | | || limited duration with less frequent requirements. | | | | || Note: While improving security, configuring touch for PIV may | | | | || have an adverse effect on usability. Note also that this configuration | | | | || does not impact already configured YubiKeys (the setting must be | | | | || present at the time of enrollment). | +------------------+-------+--------+----------------------------------------------------------------------------+ | PinCacheTimeout | DWORD | 60 || If either ``UserPinCachePolicy`` or ``ExternalPinCachePolicy`` is | | | | || set to 'timed' (1), this setting sets the number of seconds for which | | | | || the BaseCSP caches the PIN. This is only a recommendation to the | | | | || BaseCSP and is not implemented by the Minidriver. | +------------------+-------+--------+----------------------------------------------------------------------------+ | ProtectManagement| DWORD | 1 (0) || Governs the creation and storage of the PIV card management key | | | | || within a secure object to enable write access for PIV functionality. | | | | || Default ``1``. The YubiKey Minidriver generates a new card | | | | || management key and stores it in a PIN-protected object (in the | | | | || YubiKey PIV application) when the factory value is present during | | | | || PIN entry (such as during enrollment). | | | | || Set to ``0``. Disables feature. | | | | || Third party solutions (such as CMS products), while managing | | | | || YubiKeys may optionally disable this setting and assume ownership | | | | || of this feature and dependant processes (suchas enrollment). | +------------------+-------+--------+----------------------------------------------------------------------------+ | RefreshDeviceKeys| DWORD | 1 (0) || Controls the behavior of container map synchronization that | | | | || happens based on the timeout defined by RefreshWindow. | | | | || Default, ``1``, The YubiKey Minidriver (YKMD) checks that the | | | | || container map stored in the mscmap PIV object matches the | | | | || container map in the SCardCache. Additionally, the YKMD | | | | || enumerates all keys and certificates in the PIV application the | | | | || and then updates map accordingly. | | | | || Set to ``0``, disables feature. This can improve performance, | | | | || especially over RDP. However, certificates enrolled outside of the | | | | || YubiKey Minidriver might not be present in the container map as | | | | || reported to theBaseCSP(!) | +------------------+-------+--------+----------------------------------------------------------------------------+ | RefreshWindow | DWORD | 300 || Sets the time interval (in seconds) for how often the YubiKey | | | | || Minidriver (YKMD) synchronizes the container map reported to | | | | || the BaseCSP. By default the YubiKey Minidriver (YKMD) | | | | || performs synchronization when the time difference between the | | | | || last call from the BaseCSP and current time exceeds 300 seconds. | | | | || During synchronization the YKMD: | | | | || 1. Clears the BaseCSP cache (depending on setting of ManageCSPCache). | | | | || 2. Enumerates the certificates and keys in the PIV application | | | | || (depending on setting of RefreshDeviceKeys). | | | | || 3. Ensures the currently cached container map contains the same | | | | || information as the on-card container map and the list of newly | | | | || enumerated certificates. | | | | || Note: Setting a higher value than default may have a positive | | | | || impact on performance without using the heavier-handed settings | | | | || of RefreshDeviceKeys and ManageCSPCache | +------------------+-------+--------+----------------------------------------------------------------------------+ | SupportAlwaysPin | DWORD | 1 (0) || Enables and disables support for the ``Always Prompt PIN_ID`` in | | | | || the YubiKey Minidriver. The ``Always Prompt PIN_ID``, | | | | || ``PIN_CACHE_POLICY_TYPE`` is set to ``PinCacheAlwaysPrompt`` and | | | | || is assigned as the PIN for key containers that map to PIV slots | | | | || that have the ``PIN_ALWAYS`` pin policy in the YubiKey PIV | | | | || application (such as, slot 9c) in devices that support slot | | | | || metadata (YubiKey 5.2.7+). | +------------------+-------+--------+----------------------------------------------------------------------------+ | UserPinCache | DWORD | 0 (1-4)|| This setting overrides the ``PIN_CACHE_POLICY_TYPE`` for the user | | Policy | | || PIN_ID in the YubiKey Minidriver. | | | | || Default is 0 (PinCacheNormal). | | | | || This key accepts any valid ``PIN_CACHE_POLICY_TYPE`` numeric value. | | | | || See https://learn.microsoft.com/en-us/windows-hardware/drivers/smartcard/ | | | | || card-pin-operations#-pin_cache_policy_type for more information. | +------------------+-------+--------+----------------------------------------------------------------------------+