VerifyPin Method
VerifyPin(Nullable<PinUvAuthTokenPermissions>, String)
Verifies the PIN against the YubiKey using the KeyCollector
.
public void VerifyPin(Nullable<PinUvAuthTokenPermissions> permissions = null, string relyingPartyId = null)
Parameters
Type | Name | Description |
---|---|---|
System.Nullable<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 |
System.String | relyingPartyId | Some |
Exceptions
Type | Condition |
---|---|
System.OperationCanceledException | The user cancelled PIN collection. This happens when the application returns |
System.Security.SecurityException | There are no retries remaining. |
System.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.