EnrollFingerprint Method

EnrollFingerprint(String, Nullable<Int32>)

Try to enroll a fingerprint. This will require several samples. See also the User's Manual entry on Bio Enrollment.

C#
public TemplateInfo EnrollFingerprint(string friendlyName, Nullable<int> timeoutMilliseconds)

Parameters

Type Name Description
System.String friendlyName

The friendly name you want to give the template. If null or "", there will be no friendly name. You can add a friendly name later by calling the method SetBioTemplateFriendlyName(ReadOnlyMemory<Byte>, String).
System.Nullable<System.Int32> timeoutMilliseconds

The timeout the caller would like the YubiKey to enforce. This is optional and can be null. It is also possible the YubiKey ignores this value.

Returns

The TemplateInfo of the template just enrolled.

Exceptions

Type Condition
System.TimeoutException

A fingerprint was not sampled within a specified time.
System.Security.SecurityException

Too many bad samples were given before the required number of good samples were provided.
Fido2Exception

There was not enough space on the YubiKey for another template.
System.OperationCanceledException

The user canceled the operation.
System.InvalidOperationException

The YubiKey was not able to complete the process for some reason described in the exception's message.

Remarks

This method will call the KeyCollector when it needs the user to provide a fingerprint sample. Because one sample is not enough, this method will call the KeyCollector several times. When the YubiKey has collected enough samples, this method will call the KeyCollector with a request of Release. It will return a new TemplateInfo containing the template ID and the friendly name (a more detailed discussion of the friendly name is given below).

Beginning with the second sample, the KeyEntryData will include the BioEnrollSampleResult of the previous sample. In this way, the KeyCollector can report to the user any problems with the previous sample along with the number of "good" samples the YubiKey still needs in order to enroll.

When the SDK calls the KeyCollector for fingerprint enrollment, it is possible to cancel the operation. See also SignalUserCancel. In that case, this method will throw an exception. Note that it is possible (although extremely unlikely) that the SDK does not get the cancel message "in time" and a fingerprint can be enrolled nonetheless.

When a fingerprint is enrolled, the YubiKey creates a new template and gives it a ID number (the templateId, which will be unique on that YubiKey). When operating on or specifying a fingerprint, it is generally necessary to supply the templateId. However, because templateIds are binary byte arrays, it is not practical to require a user to specify a templateId. Hence, the user has the option of assigning a friendly name to each fingerprint template. In that way, a user can specify a template based on the name, and the code can use its associated templateId. If you want, you can supply the friendly name at the time the fingerprint is enrolled. If you don't want to assign a friendly name, pass in null for the friendlyName arg. In that case, you can add a friendly name later by calling the method SetBioTemplateFriendlyName(ReadOnlyMemory<Byte>, String).

The TemplateInfo this method returns will contain the provided name if the fingerprint is enrolled. It is possible the FriendlyName property is empty. This happens when the caller passes null for the friendlyName, or the name passed in is not accepted. This method will not set the friendly name if there is already a template on the YubiKey that has the name, or if the name is too long. Note that SetBioTemplateFriendlyName(ReadOnlyMemory<Byte>, String) will set the friendly name to whatever you provide, even if there is an entry with that name already.

It is possible that a given YubiKey will have no limit on the number of "bad" samples. For example, suppose a YubiKey requires 5 quality matching samples to enroll a fingerprint. It is possible some samples are rejected, such as when the finger sampled is quite a bit off center. But until 5 good samples are provided, the YubiKey will continue to ask for another, no matter how many bad ones are given. If you want a limit on bad samples, you can enforce it in the KeyCollector and use the SignalUserCancel method.

It is also possible that for some YubiKey versions, if there are too many "bad" fingerprint samples, the YubiKey's maximum sample count could be exhausted and the YubiKey "gives up" on this enrollment. In that case this method will throw an exception.

The YubiKey will also have a time limit for the user to provide a sample. This is measured from the moment the YubiKey receives the command. The SDK will call the KeyCollector announcing a fingerprint is needed at about the same time as it sends the command to the YubiKey. For some YubiKey versions, this timeout can be around 28 seconds. The FIDO2 standard specifies that a user can specify a different timeout. Hence, this method has an argument of timeoutMilliseconds. However, not all YubiKey versions support this feature. That is, it is possible a particular YubiKey will ignore this argument and use only its default timeout.