TryVerifyPin Method
TryVerifyPin(Nullable<PinUvAuthTokenPermissions>, String)
Tries to verify the PIN against the YubiKey using the KeyCollector
.
public bool TryVerifyPin(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 |
Returns
True
on success, False
if the user cancelled PIN collection, and an exception for all
other kinds of failures.
Exceptions
Type | Condition |
---|---|
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 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>, Nullable<PinUvAuthTokenPermissions>, String, out Nullable<Int32>, out Nullable<Boolean>)
Tries to verify the PIN against the YubiKey.
public bool TryVerifyPin(ReadOnlyMemory<byte> currentPin, Nullable<PinUvAuthTokenPermissions> permissions, string relyingPartyId, out Nullable<int> retriesRemaining, out Nullable<bool> rebootRequired)
Parameters
Type | Name | Description |
---|---|---|
System.ReadOnlyMemory<System.Byte> | currentPin | The FIDO2 PIN that you wish to verify. |
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 |
System.Nullable<System.Int32> | retriesRemaining | The number of PIN retries remaining before the FIDO2 application becomes locked. |
System.Nullable<System.Boolean> | rebootRequired | Indicates whether a reboot of the YubiKey (unplug and re-insert) is required before further PIN retries are allowed. |
Returns
True
if the PIN successfully verified, False
if the PIN was incorrect, and an exception for all
other kinds of failures.
Exceptions
Type | Condition |
---|---|
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 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.