TryVerifyPin Method

TryVerifyPin(PinUvAuthTokenPermissions?, string?)

Tries to verify the PIN against the YubiKey using the KeyCollector.

C#

public bool TryVerifyPin(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 and 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.

Returns

bool

True on success, False if the user cancelled PIN collection, and an exception for all other kinds of failures.

Exceptions

Type	Condition
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 TryVerifyPin 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.

TryVerifyPin(ReadOnlyMemory<byte>, PinUvAuthTokenPermissions?, string?, out int?, out bool?)

Tries to verify the PIN against the YubiKey.

C#

public bool TryVerifyPin(ReadOnlyMemory<byte> currentPin, PinUvAuthTokenPermissions? permissions, string? relyingPartyId, out int? retriesRemaining, out bool? rebootRequired)

Parameters

Type	Name	Description
ReadOnlyMemory<byte>	currentPin	The FIDO2 PIN that you wish to verify.
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, this parameter must be null and 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. If permissions is null, this parameter must also be null.
int?	retriesRemaining	The number of PIN retries remaining before the FIDO2 application becomes locked.
bool?	rebootRequired	Indicates whether a reboot of the YubiKey (unplug and re-insert) is required before further PIN retries are allowed.

Returns

bool

True if the PIN successfully verified, False if the PIN was incorrect, and an exception for all other kinds of failures.

Exceptions

Type	Condition
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 TryVerifyPin does not use the key collector. This method will only attempt to verify a single PIN and will not automatically retry. In this case, the method will return false if the PIN was incorrect. It will throw an exception in all other failure cases.

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.