EnrollFingerprint Method
EnrollFingerprint(string?, int?)
Try to enroll a fingerprint. This will require several samples. See also the User's Manual entry on Bio Enrollment.
public TemplateInfo EnrollFingerprint(string? friendlyName, int? timeoutMilliseconds)Parameters
| Type | Name | Description |
|---|---|---|
| string | friendlyName | The friendly name you want to give the template. If null or
|
| int? | 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 |
|---|---|
| TimeoutException | A fingerprint was not sampled within a specified time. |
| 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. |
| OperationCanceledException | The user canceled the operation. |
| 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.