.. 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:: +------------------+-------+--------+--------------------------------------------+ | 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 | || Upgrade | | || YubiKey is configured with 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 major security | | | | || 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 that is saved to: ``C:\Logs`` | +------------------+-------+--------+--------------------------------------------+ | DebugVerbosity | DWORD | 0 (1-3)|| Applies only when DebugOn is non-zero. | | | | || Sets the 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 | | Policy | | || ``PIN_CACHE_POLICY_TYPE`` for the 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. | +------------------+-------+--------+--------------------------------------------+ | NewKeyTouchPolicy| DWORD | 1 (2,3)|| Enables the touch policy for PIV. | | | | || Setting is optional. | | | | || | | | | || 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 (such as 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 and then updates the 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+). | +------------------+-------+--------+--------------------------------------------+ |UserPinCachePolicy| DWORD | 0 (1-4)|| This setting overrides the | | | | || ``PIN_CACHE_POLICY_TYPE`` for the user | | | | || 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. | +------------------+-------+--------+--------------------------------------------+