KeyCollector Property

KeyCollector

A callback that this class will call when it needs the YubiKey touched or a PIN to be verified.

C#

public Func<KeyEntryData, bool> KeyCollector { get; set; }

Property Value

Type	Description
System.Func<KeyEntryData, System.Boolean>

Remarks

The callback will need to read the KeyEntryData parameter which contains the information needed to determine what to collect, and methods to submit what has been collected. The callback shall return true for success or false for "cancel". A cancellation will usually happen when the user has clicked the "Cancel" button when this has been implemented in UI. That is often the case when the user has entered the wrong value a number of times, and they would like to stop trying before they exhaust their remaining retries and the YubiKey becomes blocked.

With a U2F Session, there are two situations where the SDK will call a KeyCollector: PIN and Touch. A PIN is needed only with a version 4 FIPS series YubiKey, and only if it is in FIPS mode. See the user's manual entry on FIDO U2F FIPS mode for more information on this topic. In addition, it is possible to set the PIN without using the KeyCollector, see TryVerifyPin(). With Touch, the KeyCollector will call when the YubiKey is waiting for proof of user presence. This is so that the calling app can alert the user that touch is required. There is nothing the KeyCollector needs to return to the SDK.

If your app is calling a version 4 FIPS YubiKey, it is possible to directly verify the PIN at the beginning of a session. In that case, a KeyCollector is not necessary. However, if you do not call this direct PIN verification method, and a PIN is needed later on, the SDK will throw an exception.

If you do not provide a KeyCollector and an operation requires touch, then the SDK will simply wait for the touch without informing the caller. However, it will be much more difficult to know when touch is needed. Namely, the end user will have to know that touch is needed and look for the flashing YubiKey.

This means that it is possible to perform U2F operations without a KeyCollector. However, it is very useful, especially to be able to know precisely when touch is needed.

When a touch is needed, the SDK will call the KeyCollector with a Request of KeyEntryRequest.TouchRequest. During registration or authentication, the YubiKey will not perform the operation until the user has touched the sensor. When that touch is needed, the SDK will call the KeyCollector which can then present a message (likely launch a Window) requesting the user touch the YubiKey's sensor. After the YubiKey completes the task, the SDK will call the KeyCollector with KeyEntryRequest.Release and the app can know it is time to remove the message requesting the touch.

The SDK will call the KeyCollector with a Request of Release when the process completes. In this case, the KeyCollector MUST NOT throw an exception. The Release is called from inside a finally block, and it is best practice not to throw exceptions in this context.