TryVerifyPin Method
TryVerifyPin()
Try to verify the PIN. If the user cancels, return false
public bool TryVerifyPin()Returns
A boolean, true if the PIN verifies, false if the
KeyCollector cancels.
Exceptions
| Type | Condition |
|---|---|
| InvalidOperationException | There is no |
| SecurityException | The remaining retries count indicates the PIN is blocked. |
Remarks
You need to verify the PIN only once per session. But if you have already verified, and you call this method, it will perform the verification again. If the verification fails the second time, the previous verification will be nullified.
See the PinVerified property for the current state of PIN verification.
This method will collect the PIN using the KeyCollector
delegate. If no such delegate has been set, this method will throw an
exception.
The KeyCollector has an option to cancel the operation. That
is, this TryVerifyPin method will call the KeyCollector
requesting the PIN, and it is possible that during the collection
operations, the user cancels. The KeyCollector will return to
this method noting the cancellation. In that case, this method will
return false.
Note that this is the only way to get a false return. Any
other error and this method will throw an exception. In other words,
a false return from this method means the user canceled.
This method will also set the PinVerified property of this
class. That property is a boolean. If true, the PIN has been
verified this session, otherwise it is false.
If the PIN verifies, the method will return true. If not, and
the KeyCollector cancels the process, the method will return
false and set the PinVerified property to false.
If the PIN does not verify, and the remaining retries count is not
zero, the method will call the KeyCollector again with
KeyEntryData.IsRetry set to true and
KeyEntryData.RetriesRemaining set to the number of tries
remaining until the PIN is blocked. The KeyCollector can try
to collect the PIN again, but will likely report the retries
remaining to the user and offer the option of canceling. If the
KeyCollector returns false, this method will call the
KeyCollector with Release and return false.
If the PIN does not verify, and the remaining retries count is zero,
the method will call the KeyCollector again, indicating
Release and then throw an exception. That is, once the
remaining retries count goes to zero the PIN is blocked. At this
point, this method will not try to collect the PIN any more and will
throw an exception.
If there is an error during the process, this method will simply call
the KeyCollector with Release, set the
PinVerified property to false, and throw an exception.
Note that when this method calls the KeyCollector with
Release, the return from the KeyCollector is ignored,
this method will return true or false depending on what
happened before the Release.
TryVerifyPin(ReadOnlyMemory<byte>, out int?)
Try to verify the PIN. This method will use the PIN provided, rather
than the KeyCollector.
public bool TryVerifyPin(ReadOnlyMemory<byte> pin, out int? retriesRemaining)Parameters
| Type | Name | Description |
|---|---|---|
| ReadOnlyMemory<byte> | pin | The PIN to verify. |
| int? | retriesRemaining | An output, it will be set to the number of retries remaining if the PIN is not verified. If the PIN is verified, this will be set to null. |
Returns
A boolean, true if the PIN verifies, false if not.
Exceptions
| Type | Condition |
|---|---|
| InvalidOperationException | The YubiKey had some error, such as unreliable connection. |
| OperationCanceledException | The wrong PIN was provided. |
| SecurityException | The remaining retries count indicates the PIN is blocked. |
Remarks
Normally, an application will not call any VerifyPin method.
Under the covers, the SDK determines when the PIN needs to be
verified and calls the KeyCollector. It is only at that point
the application needs to supply the PIN. The SDK will call the
application-supplied KeyCollector, indicating what it needs
(PIN, PUK, management key), and the KeyCollector does what it
needs to obtain the value requested. This system also contains a
mechanism to report if the previous value was incorrect and how many
retries remain before the value is blocked. If the PIN is never needed,
the PIN is never provided.
See the User's Manual entry on the Key Collector for a more detailed explanation of this process.
With this method, the caller provides the PIN and the
KeyCollector is never contacted.
Generally, it is necessary to verify a PIN once per session. Once the PIN is verified, any operation that required the PIN in order to execute, called during that session, will work. The exceptions include performing a private key operation using a key that was generated or imported with the PIN policy of always, changing or resetting a PIN, and setting a YubiKey or session to PIN-derived (note that you should never set a YubiKey to PIN-derived, that feature is provided only for backwards compatibility).
Some applications would like to avoid using a KeyCollector.
For such situations, this method is provided. As long as the
application does not perform an operation that requires the PIN even
if it has been verified in the session, the KeyCollector is
not needed.
Note that if the PIN is needed during the session even after the PIN
is verified using this method (see exceptions above), and no
KeyCollector is provided, the SDK will throw an exception.
The PIN is provided to this method as a
ReadOnlyMemory<byte>. It is possible to pass a
byte[], because it will be automatically cast. Most PINs will
be six to eight numbers, but the YubiKey allows any binary data. For
example, if the PIN is "123456" (the default value), what is actually
supplied to the YubiKey are the six bytes 0x31 32 33 34 35 36,
the ASCII representation of the numerals '1' through '6'. If the PIN
is "ABCDefg", then the value to send to the YubiKey is the byte array
0x41 42 43 44 65 66 67. But a PIN could also be
0xE7 05 3F 81 1C C9. Those are not ASCII characters, but a
YubiKey would accept them.
If the wrong PIN is provided, this method will return false.