TryVerifyPin Method

TryVerifyPin()

Try to verify the PIN. If the user cancels, return false

C#
public bool TryVerifyPin()

Returns

System.Boolean

A boolean, true if the PIN verifies, false if the KeyCollector cancels.

Exceptions

Type Condition
System.InvalidOperationException

There is no KeyCollector loaded, or the YubiKey had some other error, such as unreliable connection.
System.Security.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 Nullable<Int32>)

Try to verify the PIN. This method will use the PIN provided, rather than the KeyCollector.

C#
public bool TryVerifyPin(ReadOnlyMemory<byte> pin, out Nullable<int> retriesRemaining)

Parameters

Type Name Description
System.ReadOnlyMemory<System.Byte> pin

The PIN to verify.
System.Nullable<System.Int32> 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

System.Boolean

A boolean, true if the PIN verifies, false if not.

Exceptions

Type Condition
System.InvalidOperationException

The YubiKey had some error, such as unreliable connection.
System.OperationCanceledException

The wrong PIN was provided.
System.Security.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.