VerifyPin Method

VerifyPin(PinUvAuthTokenPermissions?, string?)

Verifies the PIN against the YubiKey using the KeyCollector.

public void VerifyPin(PinUvAuthTokenPermissions? permissions = null, string? relyingPartyId = null)

Parameters

Type	Name	Description
PinUvAuthTokenPermissions?	permissions	The set of operations that this auth token should be permitted to do. This parameter is allowed only if the YubiKey contains the `pinUvAuthToken` option in Options. If the YubiKey does not support this, leave the parameter `null`; the legacy GetPinTokenCommand will be used as a fallback.
string	relyingPartyId	Some `permissions` require the qualification of a relying party ID. This parameter should only be specified when a permission requires it, otherwise it should be left null. See PinUvAuthTokenPermissions for more details on which permissions require the RP ID and for which it is optional.

Exceptions

Type	Condition
OperationCanceledException	The user cancelled PIN collection. This happens when the application returns `false` in the `KeyCollector`.
SecurityException	There are no retries remaining.
InvalidOperationException	The YubiKey does not have a PIN set. --- or --- This YubiKey does not support permissions on PIN / UV auth tokens.
Fido2Exception	The YubiKey returned an error indicating that the PIN verification request could not be completed.

Remarks

If the permissions arg is null or None, then this method will obtain a PinToken. See this User's Manual entry for a deeper discussion of PinTokens on YubiKey that supports PinUvAuthTokens. If you call with no permissions but with a relying party ID, then this method will throw an exception.

A YubiKey is manufactured with no PIN set on the FIDO2 application. A PIN must be set before a user can perform most FIDO2 operations. After a PIN has been set, it must be verified against the YubiKey before privileged operations can occur. This method will perform that verification.

Unlike other applications in this SDK (such as PIV and OATH), the SDK will not automatically verify PIN or UV using the KeyCollector in methods like MakeCredential(MakeCredentialParameters) due to FIDO2's complex user verification process. Your application must call this method explicitly before attempting to perform a FIDO2 operation that requires verification.

This version of VerifyPin uses the KeyCollector delegate. You can read about key collectors in much more detail in the user's manual entry.

If the PIN was incorrectly entered, the SDK will automatically retry. The key collector will be called again allowing for another attempt at entry. Each time the key collector is called, the IsRetry member will be set to true and the RetryCount will be updated to reflect the number of retries left before the YubiKey blocks further PIN attempts. To cancel pin collection operations, simply return false in the handler for the key collector.

The PIN, while often comprised of ASCII values, can in fact contain most Unicode characters. The PIN must be encoded as a byte array using a UTF-8 encoding in Normalized Form C. See the user's manual entry on FIDO2 PINs for more information.