Class Fido2Session

Namespace: Yubico.YubiKey.Fido2

Assembly: Yubico.YubiKey.dll

Represents an active session with the FIDO2 application on the YubiKey.

public sealed class Fido2Session

Inheritance: object

Fido2Session

Remarks

When you need to perform FIDO2 operations, instantiate this class to create a session, then call on methods within the class.

Generally, you will choose the YubiKey to use by building an instance of IYubiKeyDevice. This object will represent the actual YubiKey hardware.

IYubiKeyDevice SelectYubiKey()
{
    IEnumerable<IYubiKeyDevice> yubiKeyList = YubiKey.FindAll();
    foreach (IYubiKeyDevice current in yubiKeyList)
    {
        /* Determine which YubiKey to use */
    if (selected)
    {
        return current;
    }
}

}

Once you have the YubiKey to use, you will build an instance of this Fido2Session class to represent the FIDO2 application on the hardware. Because this class implements IDisposable, use the using keyword. For example,

IYubiKeyDevice yubiKeyToUse = SelectYubiKey();
using (var fido2 = new Fido2Session(yubiKeyToUse))
{
    /* Perform FIDO2 operations. */
}

If this class is used as part of a using expression or statement, when the session goes out of scope, the Dispose method will be called to dispose of the active FIDO2 session. This will clear any application state, and ultimately release the connection to the YubiKey.

Constructors

Fido2Session(IYubiKeyDevice)

Creates an instance of Fido2Session, the object that represents the FIDO2 application on the YubiKey.

public Fido2Session(IYubiKeyDevice yubiKeyDevice)

Parameters

yubiKeyDevice IYubiKeyDevice: The object that represents the actual YubiKey on which the FIDO2 operations should be performed.

Remarks

Because this class implements IDisposable, use the using keyword. For example,

IYubiKeyDevice yubiKeyToUse = SelectYubiKey();
using (var fido2 = new Fido2Session(yubiKeyToUse))
{
    /* Perform FIDO2 operations. */
}

Exceptions

ArgumentNullException: The yubiKeyDevice argument is null.

Properties

AuthProtocol

The PIN protocol to use for all operations on this session instance.

public PinUvAuthProtocolBase AuthProtocol { get; }

Property Value

PinUvAuthProtocolBase

Remarks

By default, the SDK will ask the YubiKey for its preferred protocol and will instantiate the appropriate protocol object. A user can also override the YubiKey's choice and provide their own protocol instance by calling the SetAuthProtocol(PinUvAuthProtocolBase) method on the session class.

This property's value will always point to the auth protocol that is currently being used by the session.

AuthToken

The current PIN / UV Auth token, if present.

public ReadOnlyMemory<byte>? AuthToken { get; }

Property Value

ReadOnlyMemory<byte>?

Remarks

See the User's Manual entry for a deeper discussion of FIDO2 authentication and how AuthTokens, permissions, PIN/UV, and AuthParams fit together.

See also the User's Manual entry on the SDK's AuthToken logic. That article goes into greater detail how the SDK performs "automatic" AuthToken retrieval based on the version of the connected YubiKey, the state of the Fido2 application on the YubiKey, the input, and the state of the Fido2Session.

The PIN / UV Auth Token, or auth token for short, is created when (Try)VerifyPin or (Try)VerifyUv is called. The auth token may also have a set of permissions that restrict the use of the token. These permissions are specified when verifying the PIN or UV and are shown in the AuthTokenPermissions property.

AuthTokenPermissions

The set of permissions associated with the AuthToken.

public PinUvAuthTokenPermissions? AuthTokenPermissions { get; }

Property Value

PinUvAuthTokenPermissions?

Remarks

See the User's Manual entry for a deeper discussion of FIDO2 authentication and how AuthTokens, permissions, PIN/UV, and AuthParams fit together.

The permissions for an auth token are set when PIN or UV verification occur. This property shows the permission set of the most recent AuthToken.

There are exceptions. It is possible this property does not represent the current AuthToken's permissions. See the User's Manual entry on the SDK's AuthToken logic for a description of the "corner cases" where this property is not accurate.

Note that because an AuthToken can be expired, this property is not necessarily the permissions of a valid AuthToken that can be used to build an AuthParam that will authenticate a command. This property represents a set of permissions originally specified in the calls to AddPermissions(PinUvAuthTokenPermissions, string?), and those added by the SDK needed to perform all the operations called.

Not all YubiKeys support permissions with the auth tokens. To determine if if this feature is available, check if the pinUvAuthToken option is present and true in Options. If permissions are not supported, do not specify any permissions when verifying the PIN.

Because an AuthToken can be expired, it is possible an operation will not be able to execute with the current AuthToken. The SDK might need to retrieve a new AuthToken with the same permissions represented here during an operation.

AuthTokenRelyingPartyId

The relying party ID associated with the permissions.

public string? AuthTokenRelyingPartyId { get; }

Property Value

string

Remarks

See the User's Manual entry for a deeper discussion of FIDO2 authentication and how AuthTokens, permissions, PIN/UV, and AuthParams fit together.

If the AuthToken was obtained with a permission of MakeCredential and/or GetAssertion, a relying party ID was associated with it. It is also optional to associate a relying party with the CredentialManagement permission as well.

AuthenticatorInfo

The FIDO2 AuthenticatorInfo for the connected YubiKey.

public AuthenticatorInfo AuthenticatorInfo { get; }

Property Value

AuthenticatorInfo

Remarks

Note that it is possible for the AuthenticatorInfo to change during operations. That is, there are cases where the info says one thing, then after some operation, the info says something else. This property is updated each time one such operation is executed.

For example, if the YubiKey supports a PIN, but it is not set, then the AuthenticatorInfo.Options will contain the option "clientPin" and it will be false. After the PIN has been set, the option "clientPin" will be true.

These are not very common, but it is important to use Fido2Session.AuthenticatorInfo in your code, rather than getting a copy of the info and using it throughout.

Connection

The object that represents the connection to the YubiKey. Most applications can ignore this, but it can be used to call command classes and send APDUs directly to the YubiKey during advanced scenarios.

public IYubiKeyConnection Connection { get; }

Property Value

IYubiKeyConnection

Remarks

Most common FIDO2 operations can be done using the various methods contained on the Fido2Session class. There are some cases where you will need to issue a very specific command that is otherwise not available to you using the session's methods.

This property gives you direct access to the existing connection to the YubiKey using the IYubiKeyConnection interface. To send your own commands, call the SendCommand<TResponse>(IYubiKeyCommand<TResponse>) method like in the following example: var yubiKey = FindYubiKey();

using (var fido2 = new Fido2Session(yubiKey)) { var command = new ClientPinCommand(){ /* Set properties to your needs */ };

// Sends a command to the FIDO2 application
var response = fido2.Connection.SendCommand(command);

/* Read and handle the response */

}

KeyCollector

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

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

Property Value

Func<KeyEntryData, bool>

Remarks

With a FIDO2 Session, there are three situations where the SDK will call a KeyCollector: PIN, non-biometric touch, and biometric touch. Biometric touch is only available on YubiKey Bio Series keys.

It is possible to perform PIN operations without using the KeyCollector. Look for the overloads of TryVerifyPin, TryChangePin, and TrySetPin that take in PIN parameters. With Touch, the KeyCollector will call your application when the YubiKey is waiting for proof of user presence. This is so that your application can alert the user that touch is required. There is nothing the KeyCollector needs to return to the SDK.

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. The end user will have to know that touch is needed and look for the flashing YubiKey.

You can read more about the KeyCollector and its implementation in its user's manual entry.

Methods

AddPermissions(PinUvAuthTokenPermissions, string?)

Obtain a PinUvAuthToken that possesses the given permissions along with the current permissions. This is generally called early in a session to specify which set of permissions you expect to need for the operations you will be calling.

public void AddPermissions(PinUvAuthTokenPermissions permissions, string? relyingPartyId = null)

Parameters

permissions PinUvAuthTokenPermissions: An OR of all the permissions you expect to be needed during the session.
relyingPartyId string: If needed or wanted, how to specify the relying party in question. The default for this parameter is null, so if no arg is given, then there will be no relying party specified.

Remarks

See the User's Manual entry for a deeper discussion of FIDO2 authentication and how AuthTokens, PinTokens, permissions, PIN/UV, and AuthParams fit together.

See also the User's Manual entry on the SDK's AuthToken logic. That article goes into greater detail how this method, as well as other operations, perform "automatic" AuthToken retrieval based on the version of the connected YubiKey, the state of the Fido2 application on the YubiKey, the input, and the state of the Fido2Session.

This method will use the KeyCollector to obtain the PIN or prompt for user verification (fingerprint on YubiKey Bio). If no KeyCollector is loaded, then this method will throw an exception.

If the connected YubiKey does not support the option pinUvAuthToken, then there is likely no need to call this method. But if you do, the relyingPartyId arg must be null and the permissions arg must be None. To know if the YubiKey supports it, make this call.

IYubiKeyDevice yubiKeyToUse = SelectYubiKey();
using (var fido2Session = new Fido2Session(yubiKeyToUse))
{
    if (fido2Session.AuthenticatorInfo.GetOptionValue(
        AuthenticatorOptions.pinUvAuthToken) == OptionValue.True)
    {
        fido2Session.AddPermissions(
            PinUvAuthTokenPermissions.GetAssertion | PinUvAuthTokenPermissions.CredentialManagement,
            relyingPartyIdOfInterest);
    }
}

Generally, YubiKeys that support only FIDO2 version 2.0 will not support pinUvAuthToken and YubiKeys that support FIDO2 version 2.1, will support it. See also the User's Manual entry on the SDK's AuthToken logic for more details on using this method with a YubiKey that supports only FIDO2 version 2.0.

If the YubiKey does support pinUvAuthToken, then you can still call this method with no permissions (None) and a null relyingPartyId. In this case, the SDK will build a PinToken. See this User's Manual entry for a deeper discussion of PinTokens on YubiKey that supports PinUvAuthTokens. If you call with no permissions but with a relying party ID, then this method will throw an exception.

Note that if you pass in permissions of None, this method will obtain an AuthToken that has the same permission set currently set in the property PinUvAuthTokenPermissions, if there are any.

If the YubiKey supports PinUvAuthTokens, and this is called with permissions, then this method will determine if the YubiKey has UV capabilities, and if so, whether any bio verification has been enrolled. On the YubiKey, if there is a fingerprint enrolled, this method will first try to authenticate using UV, and if that fails, try to authenticate using PIN (see the FIDO2 standard, sections 6.5.5.7 and 6.5.5.7.3 step 3.10.3).

Calling this method will make sure that the AuthToken property in this class possesses the requested permissions along with any permissions specified in the AuthTokenPermissions property. To do so, this method will always obtain a new AuthToken, even if there is an AuthToken already in the object. More details are in the User's Manual entry on the SDK's AuthToken logic.

The MakeCredential and GetAssertion permissions require a relying party ID. That is, an AuthToken can be used to make a credential or get an assertion only for a specific relying party. If the permissions arg does not include MakeCredential or GetAssertion, then the relyingPartyId arg can be null. More details are in the User's Manual entry on the SDK's AuthToken logic.

It is not necessary to call this method at the beginning. However, if you do not make this call, then each time the SDK needs an AuthToken, it will obtain one with only one permission. That means that if you perform more than one operation, you might be called upon to obtain the PIN from the user, or require the user to perform user verification several times during this session.

An alternative to this method and the "automatic" AuthToken collection the SDK performs is to call TryVerifyPin(ReadOnlyMemory<byte>, PinUvAuthTokenPermissions?, string?, out int?, out bool?), TryVerifyUv(PinUvAuthTokenPermissions, string?) or some other verification method directly. However, because AuthTokens "expire" (see the User's Manual entry on AuthTokens), it is possible you will need to re-verify during a session. Hence, if you want to avoid this method or not build a KeyCollector, then you must write your code so that it calls, if needed, the appropriate Verify method before performing an operation. That is, you must then write your code so that it adheres to the permissions and expriy logic of FIDO2.

Exceptions

ArgumentException: The connected YubiKey does not support the permissions given, or a relying party was specified but no permissions were specified.
InvalidOperationException: The permission requires a relyingPartyId and none is given.

ChangePin()

Changes the PIN using the KeyCollector.

public void ChangePin()

Remarks

FIDO2 separates the action of setting the initial PIN from changing it. Use SetPin() to set the first PIN, and use this method to change the PIN after that. In order to change the PIN, both the current PIN and the new PIN must be supplied. A PIN cannot be removed from FIDO2. The only way to clear the PIN is to reset the entire FIDO2 application, which will result in all credentials being removed.

Several considerations must be made when collecting the PIN.

It must be encoded in UTF-8 with Normalization Form C.
It must be at least 4 Unicode code points in length.
It must not exceed 63 bytes in encoded length.

Read more about PINs here.

Exceptions

OperationCanceledException: The user cancelled PIN collection. This happens when the application returns false in the KeyCollector.
Fido2Exception: The YubiKey returned an error indicating that the change PIN request could not be completed.

ClearAuthToken()

Reset the AuthToken, AuthTokenPermissions, and AuthTokenRelyingPartyId to null, so that any future operation that retrieves an AuthToken will not use the current values.

public void ClearAuthToken()

Remarks

See the User's Manual entry for a deeper discussion of FIDO2 authentication and how AuthTokens, permissions, PIN/UV, and AuthParams fit together.

Generally you will begin a Fido2Session with a call to AddPermissions(PinUvAuthTokenPermissions, string?). If the AuthToken is expired, and an AuthToken is needed for a new operation, the SDK will obtain a new AuthToken, using the original permissions (and any new permissions needed by the operation) and the AuthTokenRelyingPartyId.

However, if you want to set the AuthTokenPermissions to a completely new value that does not have the same permission set as the current, or set it to be associated with a new relying party, or with no relying party at all, then clear the current set of values.

If you ever need to clear the AuthToken and associated properties, you will likely follow up a call to this method with a call to AddPermissions to start a new process.

DeleteCredential(CredentialId)

This performs the deleteCredential subcommand of the authenticatorCredentialManagement command. It deletes the one credential represented by the given credentialId.

public void DeleteCredential(CredentialId credentialId)

Parameters

credentialId CredentialId: The ID of the credential to delete.

Remarks

See the User's Manual entry on credential management.

If there is no credential with the given credentialId on the YubiKey, this method will do nothing.

Exceptions

Fido2Exception: The YubiKey was not able to delete the specified credential.
InvalidOperationException: The connected YubiKey does not support CredentialManagement, or the PIN was invalid, or there was no KeyCollector.
OperationCanceledException: The user canceled the operation while collecting the PIN.
SecurityException: The PIN retry count was exhausted.

Dispose()

public void Dispose()

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

friendlyName string: 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).
timeoutMilliseconds int?: 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

TemplateInfo: The TemplateInfo of the template just enrolled.

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.

Exceptions

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.

EnumerateBioEnrollments()

Get a list of all the bio enrollments on a YubiKey.

public IReadOnlyList<TemplateInfo> EnumerateBioEnrollments()

Returns

IReadOnlyList<TemplateInfo>: A new List of TemplateInfo.

Remarks

This method returns a list of TemplateInfo, one for each enrollment. If there are no enrollments, the list will be empty, it will have a Count of zero.

Exceptions

Ctap2DataException: The YubiKey could not return the list, likely because BioEnrollment is not supported.

EnumerateCredentialsForRelyingParty(RelyingParty)

This performs the enumerateCredentials (Begin and GetNextCredential) subcommands of the authenticatorCredentialManagement command. It gets a list of all the credentials associated with a specified relying party.

public IReadOnlyList<CredentialUserInfo> EnumerateCredentialsForRelyingParty(RelyingParty relyingParty)

Parameters

relyingParty RelyingParty: The relying party for which the list of credentials is requested.

Returns

IReadOnlyList<CredentialUserInfo>: A list of CredentialUserInfo objects, one for each credential.

Remarks

See the User's Manual entry on credential management.

This method returns a list of CredentialUserInfo objects. Each object contains information about one of the discoverable credentials associated with the specified relying party on the YubiKey. If there are no discoverable credentials on the YubiKey associated with the relying party, then the list will have no elements (Count will be zero).

The CredentialUserInfo object contains properties for CredentialId, CredentialPublicKey, CredProtectPolicy, and possibly LargeBlobKey,

Exceptions

InvalidOperationException: The connected YubiKey does not support CredentialManagement, or the PIN was invalid, or there was no KeyCollector.
OperationCanceledException: The user canceled the operation while collecting the PIN.
SecurityException: The PIN retry count was exhausted.

EnumerateRelyingParties()

This performs the enumerateRPs (Begin and GetNextRP) subcommands of the authenticatorCredentialManagement command. It gets a list of all the relying parties represented in all the discoverable credentials on the YubiKey.

public IReadOnlyList<RelyingParty> EnumerateRelyingParties()

Returns

IReadOnlyList<RelyingParty>: A list of RelyingParty objects.

Remarks

See the User's Manual entry on credential management.

This method returns a list of RelyingParty objects. Each object contains information about one of the relying parties represented on the YubiKey. If there are no discoverable credentials on the YubiKey, then the list will have no elements (Count will be zero).

Note that other FIDO2 operations require the "RelyingPartyIdHash", which is one of the properties of the RelyingParty object.

Exceptions

InvalidOperationException: The connected YubiKey does not support CredentialManagement, or the PIN was invalid, or there was no KeyCollector.
OperationCanceledException: The user canceled the operation while collecting the PIN.
SecurityException: The PIN retry count was exhausted.

GetAssertions(GetAssertionParameters)

Gets one or more assertions for a particular relying party.

Note

You must supply a GetAssertionParameters object to this method, however, you do not need to set the PinUvAuthParam property, the SDK will do so.

public IReadOnlyList<GetAssertionData> GetAssertions(GetAssertionParameters parameters)

Parameters

parameters GetAssertionParameters: An appropriately populated GetAssertionParameters structure that follows all of the rules set forth by that object.

Returns

IReadOnlyList<GetAssertionData>: A collection of objects that contain the credential assertion and supporting data.

Remarks

Detailed information about the parameters structure and its expected values can be found on the GetAssertionParameters page.

To get an assertion requires "user presence", which for a YubiKey is touch. This method will call the KeyCollector when touch is required (KeyEntryRequest.TouchRequest).

The SDK will automatically perform PIN or user verification using the KeyCollector if needed. That is, if this method determines that authentication has been successfully completed, it will not need the PIN or fingerprint, so will not call the KeyCollector. However, if it needs to perform authentication, it will request user verification and/or a PIN using the KeyCollector.

Note that because the SDK will make the appropriate authentication calls, it will build the PinUvAuthParam in the GetAssertionParameters input arg, so you do not need to do so.

It is still possible to call this method with a KeyCollector that does not collect a PIN (you will need to have one that supports at least KeyEntryRequest.TouchRequest). You must simply make sure the appropriate Verify method has been called. See the User's Manual entries on AuthTokens and the SDK AuthToken logic for more information on when to verify. If you do not provide a KeyCollector that can collect the PIN, and the method is not able to perform because of an authentication failure, it will throw an exception.

If there are no credentials associated with the relying party, this method will return a List with no entries (Count = 0).

Exceptions

ArgumentNullException: The parameters argument was null.
Fido2Exception: The YubiKey could not complete the operation, likely because of a wrong PIN or fingerprint.
TimeoutException: The YubiKey either required touch for a user presence check or a biometric touch for user authentication. The YubiKey timed out waiting for this action to be performed.

GetBioModality()

Get the biometric method the YubiKey uses. If the YubiKey is not a Bio series device, this will return "None".

public BioModality GetBioModality()

Returns

BioModality: A BioModality value, indicating the biometric method or else "None" for non-Bio series devices.

Remarks

Note that the UvModality property also indicates the modality. It is defined as a bit field with the specific bits defined in the FIDO standard's Registry of Predefined Values, section 3.1. For example, in that bit field, the bit in position 1 (the integer 2) is defined as USER_VERIFY_FINGERPRINT_INTERNAL.

GetCredentialMetadata()

This performs the getCredsMetadata subcommand of the authenticatorCredentialManagement command. It gets metadata for all the credentials on the YubiKey.

public (int discoverableCredentialCount, int remainingCredentialCount) GetCredentialMetadata()

Returns

(int discoverableCredentialCount, int remainingCredentialCount): Two integers, the number of discoverable credentials in the YubiKey's FIDO2 application and the number of discoverable credentials for which it has space.

Remarks

See the User's Manual entry on credential management.

This method returns a Tuple of two integers, the number of discoverable credentials and the number of "slots" remaining. The number of slots is the number of discoverable credentials the YubiKey can still hold.

In order to execute, this method will need a PIN/UV auth param, which is built using an AuthToken, which itself is built from the PIN and the permissions, or UV and permissions. This method will need an AuthToken with the permission CredentialManagement.

If there is no Fido2Session property AuthToken, or it does not work (i.e. it is expired or does not have the appropriate permission), this method will use the KeyCollector to obtain a new one.

If you do not want to use a KeyCollector, you must verify the PIN before calling, making sure the CredentialManagement permission is set. See TryVerifyPin(ReadOnlyMemory<byte>, PinUvAuthTokenPermissions?, string?, out int?, out bool?)

bool isVerified = fido2Session.TryVerifyPin(
    currentPin, PinUvAuthTokenPermissions.CredentialManagement,
    null, out int _, out bool _);

Exceptions

InvalidOperationException: The connected YubiKey does not support CredentialManagement, or the PIN was invalid, or there was no KeyCollector.
OperationCanceledException: The user canceled the operation while collecting the PIN.
SecurityException: The PIN retry count was exhausted.

GetFingerprintSensorInfo()

Get the fingerprint sensor info, which is the "fingerprint kind" (touch or swipe), maximum capture count, and the maximum length, in bytes, of a template friendly name.

public FingerprintSensorInfo GetFingerprintSensorInfo()

Returns

FingerprintSensorInfo: A FingerprintSensorInfo object.

Remarks

If the connected YubiKey does not have a fingerprint sensor, this method will throw an exception. Hence, it would be a good idea to call GetBioModality() and verify the modality is Fingerprint before calling this method.

Exceptions

NotSupportedException: The connected YubiKey does not support reading fingerprints.

GetSerializedLargeBlobArray()

Get the current Serialized Large Blob Array out of the YubiKey. See also the User's Manual entry on large blobs.

public SerializedLargeBlobArray GetSerializedLargeBlobArray()

Returns

SerializedLargeBlobArray: A new instance of the SerializedLargeBlobArray class containing the currently stored large blob data.

Remarks

Note that this feature is not available on all YubiKeys. To determine if large blobs are supported on a YubiKey, check the Options in the AuthenticatorInfo property of this class. For example,

OptionValue optionValue =
    fido2Session.AuthenticatorInfo.GetOptionValue(AuthenticatorOptions.largeBlobs);
if (optionValue != OptionValue.True)
{
    return;
}
int maxLargeBlobsLength = authInfo.MaximumSerializedLargeBlobArray ?? 0;

A serialized large blob array is the large blob array concatenated with the digest of the array. The digest is the first 16 bytes (left 16 bytes) of the SHA-256 of the CBOR-encoded array.

Once you have the object containing the data, it is possible to read each entry by decrypting, using the appropriate LargeBlobKey. Each entry is encrypted using the large blob key of one of the credentials (each credential has a different large blob key). The standard specifies obtaining a large blob key (likely from a GetAssertion call), and trying to decrypt each entry in the array using that key. If it succeeds, that entry is associated with the credential and the decrypted data will be returned. See also TryDecrypt(ReadOnlyMemory<byte>, out Memory<byte>)

A YubiKey is manufactured with the initial large blob data, which is an array of zero elements plus the digest of the CBOR-encoding of a zero-element array. An array with zero elements is simply the single byte 0x80. Hence, there will always be a current large blob array to retrieve.

The standard specifies that when reading a serialized large blob array, a client must verify the digest. If the digest does not verify, the standard specifically says, "the configuration is corrupt and the platform MUST discard it and act as if the initial serialized large-blob array was received." This method will verify the digest value. If the digest does not verify, this method will return a new SerializedLargeBlobArray containing the initial value. It will not overwrite the data on the YubiKey, so you can still use the GetLargeBlobCommand to get the raw data.

Because writing to the large blob area in a YubiKey means overwriting the existing data, it is recommended that to add to, remove from, or "edit" the large blob data, the caller should get the current large blob array, operate on the resulting SerializedLargeBlobArray, and then call SetSerializedLargeBlobArray(SerializedLargeBlobArray) with the updated data. Even if your application has not updated the large blob array, it is possible another application has stored data and you likely do not want to overwrite that data.

Exceptions

NotSupportedException: The YubiKey selected does not support large blobs.

MakeCredential(MakeCredentialParameters)

Creates a FIDO2 credential on the YubiKey given a parameters object.

public MakeCredentialData MakeCredential(MakeCredentialParameters parameters)

Parameters

parameters MakeCredentialParameters: A fully populated MakeCredentialParameters structure that follows all of the rules set forth by that object.

Returns

MakeCredentialData: An object containing all of the relevant information returned by the YubiKey after calling MakeCredential. This includes the public key for the credential itself, along with supporting information like the attestation statement and other authenticator data.

Remarks

Detailed information about the parameters structure and its expected values can be found on the MakeCredentialParameters page. Note that a UserEntity is a required element in order to make a credential. The standard specifies that the UserEntity is made up of an ID, a Name, and a DisplayName. The standard also says the Name and DisplayName are optional. It should be possible to make a credential using a UserEntity that contains only an ID. However, YubiKeys prior to version 5.3.0 require a Name in order to make a credential.

To make a credential requires "user presence", which for a YubiKey is touch. This method will call the KeyCollector when touch is required (KeyEntryRequest.TouchRequest).

Exceptions

ArgumentNullException: The parameters argument was null.
Fido2Exception: The YubiKey could not complete the operation, likely because of a wrong PIN or fingerprint.
TimeoutException: The YubiKey either required touch for a user presence check or a biometric touch for user verification. The YubiKey timed out waiting for this action to be performed.

SetAuthProtocol(PinUvAuthProtocolBase)

Overrides the default PIN/UV Auth protocol (which is determined by the YubiKey and SDK).

public void SetAuthProtocol(PinUvAuthProtocolBase authProtocol)

Parameters

authProtocol PinUvAuthProtocolBase: The PIN/UV auth protocol instance to use for this session class.

Remarks

Call this method with an instance of a class that derives PinUvAuthProtocolBase - either PinUvAuthProtocolOne or PinUvAuthProtocolTwo. When called, this method will replace the existing reference stored as AuthProtocol with the one that was passed to this function. The SDK will automatically dispose of the previous protocol if it was the default protocol created by the SDK. Otherwise, it will not. The caller of this function owns the lifetime of any protocol passed into the session - the SDK will not dispose of any user-set auth protocol.

The auth protocol is not remembered across sessions. That is - if you call this method on session A, and later create a session B, the session B will be using the default auth protocol. You would need to call this method on both session instances to override the default behavior.

Exceptions

ArgumentNullException: The value specified by authProtocol is null.

SetBioTemplateFriendlyName(ReadOnlyMemory<byte>, string)

Set the friendly name of a template. If the template already has a friendly name, this will replace it.

public void SetBioTemplateFriendlyName(ReadOnlyMemory<byte> templateId, string friendlyName)

Parameters

templateId ReadOnlyMemory<byte>: The ID for the template which will be given the name.
friendlyName string: The friendly name you want to give the template.

Remarks

If the template already has a friendly name, this method will replace it.

This method will not check to see if the YubiKey has a fingerprint entry with the given name already. In other words, using this method allows you to use the same friendly name for more than one template.

Exceptions

ArgumentException: The YubiKey rejects the friendly name, likely because it is too long.

SetPin()

Sets the initial FIDO2 PIN using the KeyCollector. To change an existing PIN, use the ChangePin() function.

public void SetPin()

Remarks

The Yubikey is manufactured with no default PIN set on the FIDO2 application. To configure a YubiKey's initial PIN, use this function. This function will only succeed if no PIN is currently configured. To change an existing PIN, use the ChangePin() method instead. Once set, a PIN cannot be removed without resetting the FIDO2 application. The reset operation will remove the PIN and clear all registered credentials.

Several considerations must be made when collecting the PIN.

It must be encoded in UTF-8 with Normalization Form C.
It must be at least 4 Unicode code points in length.
It must not exceed 63 bytes in encoded length.

Read more about PINs here.

Exceptions

SecurityException: The YubiKey already has a PIN set. This function cannot be used to change the PIN.
OperationCanceledException: The user cancelled PIN collection. This happens when the application returns false in the KeyCollector.

SetSerializedLargeBlobArray(SerializedLargeBlobArray)

Set the Serialized Large Blob Array in the YubiKey to contain the data in the input serializedLargeBlobArray. See also the User's Manual entry on large blobs.

public void SetSerializedLargeBlobArray(SerializedLargeBlobArray serializedLargeBlobArray)

Parameters

serializedLargeBlobArray SerializedLargeBlobArray: The object containing the data to store.

Remarks

Note that this feature is not available on all YubiKeys. To determine if large blobs are supported on a YubiKey, check the Options in the AuthenticatorInfo property of this class. For example,

OptionValue optionValue =
    fido2Session.AuthenticatorInfo.GetOptionValue(AuthenticatorOptions.largeBlobs);
if (optionValue != OptionValue.True)
{
    return;
}
int maxLargeBlobsLength = authInfo.MaximumSerializedLargeBlobArray ?? 0;

This method will overwrite the current contents of the large blob data on the YubiKey. Hence, an application should get the current contents (GetSerializedLargeBlobArray()) and add to, remove from, or "edit" the contents. Then use this method to store the updated large blob.

This method will need the PIN to have been verified with the LargeBlobWrite. If that permission is not set, this method will verify the PIN (even if it had already been verified during this session) with the permission, and use the KeyCollector in order to obtain the PIN. If you do not want this method to call the KeyCollector you must verify the PIN explicitly (see TryVerifyPin) with the permissions argument set with LargeBlobWrite. You will likely want to get the current permissions (AuthTokenPermissions) and add LargeBlobWrite. For example,

PinUvAuthTokenPermissions permissions = AuthTokenPermissions ?? PinUvAuthTokenPermissions.None;
if (!permissions.HasFlag(PinUvAuthTokenPermissions.LargeBlobWrite))
{
    permissions |= PinUvAuthTokenPermissions.LargeBlobWrite;
    bool isVerified = TryVerifyPin(
       currentPin, permissions, null, out int retriesRemaining, out bool rebootRequired);
}

Exceptions

Fido2Exception: The YubiKey could not complete the operation, likely because of a wrong PIN or fingerprint.

TryChangePin()

Tries to change the PIN using the KeyCollector.

public bool TryChangePin()

Returns

bool: True on success, False if the user cancelled PIN collection, and an exception for all other kinds of failures.

Remarks

Several considerations must be made when collecting the PIN.

It must be encoded in UTF-8 with Normalization Form C.
It must be at least 4 Unicode code points in length.
It must not exceed 63 bytes in encoded length.

Read more about PINs here.

Exceptions

Fido2Exception: The YubiKey returned an error indicating that the change PIN request could not be completed.

TryChangePin(ReadOnlyMemory<byte>, ReadOnlyMemory<byte>)

Tries to change the PIN.

public bool TryChangePin(ReadOnlyMemory<byte> currentPin, ReadOnlyMemory<byte> newPin)

Parameters

currentPin ReadOnlyMemory<byte>

The existing PIN encoded using UTF-8 in Normalization Form C.

newPin ReadOnlyMemory<byte>

The new PIN to program onto the YubiKey. The new PIN:

Must be encoded in UTF-8 with Normalization Form C.
Must be at least 4 Unicode code points in length.
Must not exceed 63 bytes in encoded length.

Read more about PINs here.

Returns

bool: True, if successful. Otherwise false.

Remarks

Exceptions

Fido2Exception: The YubiKey returned an error indicating that the change PIN request could not be completed.

TryEnableEnterpriseAttestation()

Try to set the YubiKey to enable enterprise attestation. If the YubiKey selected does not support enterprise attestation, this method will return false.

public bool TryEnableEnterpriseAttestation()

Returns

bool: A boolean, true if the YubiKey now has enterprise attestation enabled, false if the YubiKey does not support this feature.

Remarks

See the FIDO2 standard, section 7.1, for a discussion of enterprise attestation.

It is possible to enable enterprise attestation only if the "ep" option is present. If the "ep" option is not present, this method will return false.

If the "ep" option is present, this method will make sure the value is true. That is, if "ep" is false, this will call on the YubiKey to set it to true. If "ep" is already true, after calling this method, the value will still be true.

Note that once a YubiKey has been set to enable enterprise attestation, it is not possible to disable it, other than resetting the entire Fido2 application on the YubiKey.

The enable enterprise attestation operation requires a PinUvAuthToken with permission "acfg" (Authenticator Configuration). If the "ep" option is present and false, this method will need the AuthToken. Otherwise ("ep" is present and true or "ep" is not supported), this method will not perform any operation that requires an AuthToken. If the method needs an AuthToken, it will get one using the KeyCollector. If you do not want to use a KeyCollector, make sure you verify the PIN or UV with the AuthenticatorConfiguration permission before calling this method.

Exceptions

Ctap2DataException: The YubiKey could not perform the operation, even though enterprise attestation is supported.

TryRemoveBioTemplate(ReadOnlyMemory<byte>)

Try to remove a template from a YubiKey. If there is no enrollment on the YubiKey for the given template ID, this method will do nothing and return true.

public bool TryRemoveBioTemplate(ReadOnlyMemory<byte> templateId)

Parameters

templateId ReadOnlyMemory<byte>: The ID for the template which will be removed.

Returns

bool: A boolean, true if the entry was removed, false otherwise.

TrySetPin()

Tries to set the initial FIDO2 PIN using the KeyCollector. To change an existing PIN, use the TryChangePin() function.

public bool TrySetPin()

Returns

bool: True on success, False if the user cancelled PIN collection, and an exception for all other kinds of failures.

Remarks

The Yubikey is manufactured with no default PIN set on the FIDO2 application. To initially configure a PIN, use this function. This function will only succeed if no PIN is currently configured. To change an already set PIN, use the ChangePin() method instead. Once set, a PIN cannot be removed without resetting the FIDO2 application. This operation will unset the PIN as well as clear all registered credentials.

Several considerations must be made when collecting the PIN.

It must be encoded in UTF-8 with Normalization Form C.
It must be at least 4 Unicode code points in length.
It must not exceed 63 bytes in encoded length.

Read more about PINs here.

Exceptions

SecurityException: The YubiKey already has a PIN set. This function cannot be used to change the PIN.

TrySetPin(ReadOnlyMemory<byte>)

Tries to set the initial FIDO2 PIN. To change an existing PIN, use the TryChangePin() function.

public bool TrySetPin(ReadOnlyMemory<byte> newPin)

Parameters

newPin ReadOnlyMemory<byte>: The PIN to program onto the YubiKey. It must be encoded in UTF-8 with Normalization Form C. It must be at least 4 Unicode code points in length, and not to exceed 63 bytes in encoded length. Read more about PINs here.

Returns

bool: True on success, False if the YubiKey has a PIN already set, and an exception for all other kinds of failures.

Remarks

TrySetPinConfig(int?, IReadOnlyList<string>?, bool?)

Perform the authenticatorConfig subcommand of setMinPINLength, which will set the minimum PIN length, and/or replace the list of relying parties that are allowed to see the minimum PIN length, and/or specify that the user must change the PIN.

public bool TrySetPinConfig(int? newMinPinLength = null, IReadOnlyList<string>? relyingPartyIds = null, bool? forceChangePin = null)

Parameters

newMinPinLength int?: The new PIN length, measured in code points. See the User's Manual entry on the FIDO2 PIN for more information on PIN composition. Pass in null to indicate the command should not change the minimum PIN length.
relyingPartyIds IReadOnlyList<string>: A list of strings that are the relying party IDs for those RPs that are allowed to see the minimum PIN length. Pass in null to indicate the command should not add any RP IDs.
forceChangePin bool?: If you want to set the YubiKey to require the user change the PIN before the next verification event, pass in true. If you pass in null or false, this command will consider the force PIN option not taken.

Returns

bool: A boolean, true if the YubiKey was able to set the YubiKey with the given input data, false if the YubiKey does not support this feature.

Remarks

This method will perform the operation only if the "setMinPINLength" option is present and set to true. Otherwise, it will return false

There are up to three elements to set with this command: a new minimum PIN length, a new list of relying party IDs, and an indication to require the user change the PIN. All three are optional, although this command will do nothing if none are set (i.e. the three args are null, null, null).

If you want to set an element, provide a value for the corresponding argument, otherwise, pass in null.

If you want to force a PIN change, pass in true for the forceChangePin arg. If you pass in false, this class will consider it the same as null. That is, the forceChangePin element of this command is optional, meaning the command does not need to include the element (i.e. leave it blank in the command sent to the YubiKey). If you pass in false, this method will send the command without that element (i.e., it will be left blank).

The YubiKey's FIDO2 application is manufactured with a minimum PIN length. Users that want a different length can call this command. However, it is not possible to set the minimum PIN length to a value less than the current minimum. The only way to possibly set a shorter minimum PIN length is to reset the entire FIDO2 application on the given YubiKey. Even then, after reset, the minimum PIN will be the default length with which the YubiKey was originally manufactured.

The PIN length is measured in code points. See the User's Manual entry on the FIDO2 PIN for more information on PIN composition.

Note that the standard specifies that a PIN cannot be less than 4 Unicode characters and no more than 63 bytes when encoded as UTF-8. Hence, there are limits to the new minimum PIN length.

The list of RP IDs will specify that any RP on the list is allowed to see the minimum PIN length of a YubiKey. That will be visible only during the MakeCredential process. Generally, it is used so that an RP will refuse to provide a credential to an authenticator if the minimum PIN length is too low.

It is possible for a YubiKey to be manufactured with a pre-configured list of RP IDs. That list will never change, even after reset. If RP IDs are added using the SetMinPINLength command, they will be IDs in addition to the pre-configured list.

If RP IDs are added using this command, they will replace any RP IDs that had been added during a previous call to this command. It will not replace the pre-configured list. Note that there is no way to get the current list.

If the minimum PIN length is set, and if the current PIN is smaller than this value, then the YubiKey will require the user to change the PIN. It will not verify the current PIN and any operation that requires PIN verification will fail until the PIN is changed to a value that meets the new requirement. For example, suppose the current minimum PIN length is 4 and you have a PIN of length 6. You set the minimum PIN length to 7, but do not set forceChangePin (you pass in null for that arg). The YubiKey will still require the user change the PIN.

If forceChangePin is true, then the caller is requiring the user to change the PIN, no matter what.

You can know if a PIN must be changed (either because the min PIN length is now longer than the existing PIN or the forceChangePin was set), look at the ForcePinChange property in the AuthenticatorInfo.

Note that if you pass in null for all three arguments, this method will still check to see if the feature is supported and return false if it is not. If the feature is supported, this method will do nothing.

Exceptions

Ctap2DataException: The YubiKey could not perform the operation, even though the set min PIN length feature is supported. For example, if the input newMinPinLength arg is less than the current min PIN length.

TryToggleAlwaysUv()

Try to toggle the YubiKey's "alwaysUv" option (set to false if currently true or set to true if currently false. If the YubiKey selected does not support the "alwaysUv" option, this method will return false.

public bool TryToggleAlwaysUv()

Returns

bool: A boolean, true if the YubiKey was able to toggle the "alwaysUv" and "makeCredUvNotReqd" options, false if the YubiKey does not support this feature.

Remarks

See the FIDO2 standard, section 7.2, for a discussion of the always UV feature.

It is possible to toggle the feature only if the "alwaysUv" option is present on the YubiKey. If the "alwaysUv" option is not present, this method will return false.

This method will also toggle the "makeCredUvNotReqd" option as well. This option will almost certainly be the opposite of "alwaysUv".

Before calling this method, you should check the "alwaysUv" option in the AuthenticatorInfo. If it is already true and you want it true, don't call this method.

OptionValue optionValue = fido2Session.AuthenticatorInfo.GetOptionValue(
    AuthenticatorOptions.alwaysUv);
if (optionValue == OptionValue.False)
{
    _ = fido2Session.TryToggleAlwaysUv();
}

The enable toggle always UV operation requires a PinUvAuthToken with permission "acfg" (Authenticator Configuration). If the "alwaysUv" option is present, this method will need the AuthToken. If the method needs an AuthToken, it will get one using the KeyCollector. If you do not want to use a KeyCollector, make sure you verify the PIN or UV with thee AuthenticatorConfiguration permission before calling this method.

Exceptions

Ctap2DataException: The YubiKey could not perform the operation, even though the always UV toggle feature is supported.

TryVerifyPin(PinUvAuthTokenPermissions?, string?)

Tries to verify the PIN against the YubiKey using the KeyCollector.

public bool TryVerifyPin(PinUvAuthTokenPermissions? permissions = null, string? relyingPartyId = null)

Parameters

permissions PinUvAuthTokenPermissions?: The set of operations that this auth token should be permitted to do. This parameter is allowed only if the YubiKey contains the pinUvAuthToken option in Options. If the YubiKey does not support this, leave the parameter null and the legacy GetPinTokenCommand will be used as a fallback.
relyingPartyId string: Some permissions require the qualification of a relying party ID. This parameter should only be specified when a permission requires it, otherwise it should be left null. See PinUvAuthTokenPermissions for more details on which permissions require the RP ID and for which it is optional.

Returns

bool: True on success, False if the user cancelled PIN collection, and an exception for all other kinds of failures.

Remarks

If the permissions arg is null or None, then this method will obtain a PinToken. See this User's Manual entry for a deeper discussion of PinTokens on YubiKey that supports PinUvAuthTokens. If you call with no permissions but with a relying party ID, then this method will throw an exception.

A YubiKey is manufactured with no PIN set on the FIDO2 application. A PIN must be set before a user can perform most FIDO2 operations. After a PIN has been set, it must be verified against the YubiKey before privileged operations can occur. This method will perform that verification.

Unlike other applications in this SDK (such as PIV and OATH), the SDK will not automatically verify PIN or UV using the KeyCollector in methods like MakeCredential(MakeCredentialParameters) due to FIDO2's complex user verification process. Your application must call this method explicitly before attempting to perform a FIDO2 operation that requires verification.

This version of TryVerifyPin uses the KeyCollector delegate. You can read about key collectors in much more detail in the user's manual entry.

If the PIN was incorrectly entered, the SDK will automatically retry. The key collector will be called again allowing for another attempt at entry. Each time the key collector is called, the IsRetry member will be set to true and the RetryCount will be updated to reflect the number of retries left before the YubiKey blocks further PIN attempts. To cancel pin collection operations, simply return false in the handler for the key collector.

The PIN, while often comprised of ASCII values, can in fact contain most Unicode characters. The PIN must be encoded as a byte array using a UTF-8 encoding in Normalized Form C. See the user's manual entry on FIDO2 PINs for more information.

Exceptions

SecurityException: There are no retries remaining.
InvalidOperationException: The YubiKey does not have a PIN set. --- or --- This YubiKey does not support permissions on PIN / UV auth tokens.
Fido2Exception: The YubiKey returned an error indicating that the PIN verification request could not be completed.

TryVerifyPin(ReadOnlyMemory<byte>, PinUvAuthTokenPermissions?, string?, out int?, out bool?)

Tries to verify the PIN against the YubiKey.

public bool TryVerifyPin(ReadOnlyMemory<byte> currentPin, PinUvAuthTokenPermissions? permissions, string? relyingPartyId, out int? retriesRemaining, out bool? rebootRequired)

Parameters

currentPin ReadOnlyMemory<byte>: The FIDO2 PIN that you wish to verify.
permissions PinUvAuthTokenPermissions?: The set of operations that this auth token should be permitted to do. This parameter is allowed only if the YubiKey contains the pinUvAuthToken option in Options. If the YubiKey does not support this, this parameter must be null and the legacy GetPinTokenCommand will be used as a fallback.
relyingPartyId string: Some permissions require the qualification of a relying party ID. This parameter should only be specified when a permission requires it, otherwise it should be left null. See PinUvAuthTokenPermissions for more details on which permissions require the RP ID and for which it is optional. If permissions is null, this parameter must also be null.
retriesRemaining int?: The number of PIN retries remaining before the FIDO2 application becomes locked.
rebootRequired bool?: Indicates whether a reboot of the YubiKey (unplug and re-insert) is required before further PIN retries are allowed.

Returns

bool: True if the PIN successfully verified, False if the PIN was incorrect, and an exception for all other kinds of failures.

Remarks

This version of TryVerifyPin does not use the key collector. This method will only attempt to verify a single PIN and will not automatically retry. In this case, the method will return false if the PIN was incorrect. It will throw an exception in all other failure cases.

Exceptions

InvalidOperationException: The YubiKey does not have a PIN set. --- or --- This YubiKey does not support permissions on PIN / UV auth tokens.
Fido2Exception: The YubiKey returned an error indicating that the PIN verification request could not be completed.

TryVerifyUv(PinUvAuthTokenPermissions, string?)

Tries to Perform a User Verification (UV) check on the YubiKey using the onboard biometric sensor. This method is only supported on YubiKey Bio Series devices. The permissions argument must be something other than None.

public bool TryVerifyUv(PinUvAuthTokenPermissions permissions, string? relyingPartyId = null)

Parameters

permissions PinUvAuthTokenPermissions: The set of operations that this auth token should be permitted to do. This parameter cannot be None for UvVerification.
relyingPartyId string: Some permissions require the qualification of a relying party ID. This parameter should only be specified when a permission requires it, otherwise it should be left null. See PinUvAuthTokenPermissions for more details on which permissions require the RP ID and for which it is optional.

Returns

bool: A boolean, true if the verification succeeds, false if the user cancels.

Remarks

This method will call the KeyCollector to prompt the user to provide the fingerprint. If there is no KeyCollector, this method will throw an exception.

When verifying using Uv, the caller must provide a valid permission. If the input permissions arg is None, this method will throw an exception.

A YubiKey is manufactured with no PIN and no biometric templates set. A PIN must be set before a user can register fingerprints. After a PIN has been set, a user can enroll one or more fingers using their platform or operating system's built in registration mechanism.

Once both a PIN has been set and a fingerprint has been registered, a user can perform verification. This method initiates the biometric (or user verification) process. If the user cannot match a valid finger within the allowed number of retries, it is best practice to fall back to PIN verification.

If the YubiKey was unable to verify a registered fingerprint, the SDK will automatically retry. The key collector will be called again to notify your app that touch is required. Each time the key collector is called, the IsRetry member will be set to true and the RetryCount will be updated to reflect the number of retries left before the YubiKey blocks further UV attempts. To cancel UV collection operations, call the SignalUserCancel delegate. When the retries have been exhausted, a SecurityException will be thrown. This, along with user cancellation, are indicators that your application should switch to verification with PIN.

If the user cancels the operation, this method will return false. If the YubiKey times out, this method will throw a TimeoutException.

Exceptions

InvalidOperationException: The YubiKey does not support onboard user-verification, or else it does support it but there are no fingerprints enrolled.
SecurityException: The YubiKey has blocked fingerprint verification because of too many "bad" readings.
TimeoutException: The YubiKey timed out waiting for the user to supply a fingerprint.
Fido2Exception: The permissions arg was None or the YubiKey was not able to complete the process for some reason described in the exception's message.

UpdateUserInfoForCredential(CredentialId, UserEntity)

This performs the updateUserInformation subcommand of the authenticatorCredentialManagement command. It replaces the user info in the credential represented by the given credentialId with the given user data.

public void UpdateUserInfoForCredential(CredentialId credentialId, UserEntity newUserInfo)

Parameters

credentialId CredentialId: The ID of the credential to update.
newUserInfo UserEntity: An object containing the information that will replace the currently stored info.

Remarks

See the User's Manual entry on credential management.

This method will replace all the user information currently stored against the credentialId on the YubiKey. That is, it does not "edit" the information. Hence, the userEntity you supply should contain all the information you want stored, even if some of that information is currently stored on the YubiKey.

If there is no credential with the given credentialId on the YubiKey, this method will throw an exception

Exceptions

Fido2Exception: There was no credential with the given ID.
InvalidOperationException: The connected YubiKey does not support CredentialManagement, or the PIN was invalid, or there was no KeyCollector.
OperationCanceledException: The user canceled the operation while collecting the PIN.
SecurityException: The PIN retry count was exhausted.

VerifyPin(PinUvAuthTokenPermissions?, string?)

Verifies the PIN against the YubiKey using the KeyCollector.

public void VerifyPin(PinUvAuthTokenPermissions? permissions = null, string? relyingPartyId = null)

Parameters

permissions PinUvAuthTokenPermissions?: The set of operations that this auth token should be permitted to do. This parameter is allowed only if the YubiKey contains the pinUvAuthToken option in Options. If the YubiKey does not support this, leave the parameter null; the legacy GetPinTokenCommand will be used as a fallback.
relyingPartyId string: Some permissions require the qualification of a relying party ID. This parameter should only be specified when a permission requires it, otherwise it should be left null. See PinUvAuthTokenPermissions for more details on which permissions require the RP ID and for which it is optional.

Remarks

This version of VerifyPin uses the KeyCollector delegate. You can read about key collectors in much more detail in the user's manual entry.

Exceptions

OperationCanceledException: The user cancelled PIN collection. This happens when the application returns false in the KeyCollector.
SecurityException: There are no retries remaining.
InvalidOperationException: The YubiKey does not have a PIN set. --- or --- This YubiKey does not support permissions on PIN / UV auth tokens.
Fido2Exception: The YubiKey returned an error indicating that the PIN verification request could not be completed.

VerifyUv(PinUvAuthTokenPermissions, string?)

Performs a User Verification (UV) check on the YubiKey using the onboard biometric sensor. This method is only supported on YubiKey Bio Series devices. Uses the KeyCollector for touch prompting.

public void VerifyUv(PinUvAuthTokenPermissions permissions, string? relyingPartyId = null)

Parameters

permissions PinUvAuthTokenPermissions: The set of operations that this auth token should be permitted to do.
relyingPartyId string: Some permissions require the qualification of a relying party ID. This parameter should only be specified when a permission requires it, otherwise it should be left null. See PinUvAuthTokenPermissions for more details on which permissions require the RP ID and for which it is optional.

Remarks

If the YubiKey was unable to verify a registered fingerprint, the SDK will automatically retry. The key collector will be called again to notify your app that touch is required. Each time the key collector is called, the IsRetry member will be set to true and the RetryCount will be updated to reflect the number of retries left before the YubiKey blocks further UV attempts. To cancel UV collection operations, simply return false in the handler for the key collector. When the retries have been exhausted, a `SecurityException` will be thrown. This, along with user cancellation, are indicators that your application should switch to verification with PIN.

Exceptions

OperationCanceledException: The user cancelled UV collection. This happens when the application returns false in the KeyCollector.

Table of Contents

Class Fido2Session

Remarks

Constructors

Fido2Session(IYubiKeyDevice)

Parameters

Remarks

Exceptions

Properties

AuthProtocol

Property Value

Remarks

AuthToken

Property Value

Remarks

AuthTokenPermissions

Property Value

Remarks

AuthTokenRelyingPartyId

Property Value

Remarks

AuthenticatorInfo

Property Value

Remarks

Connection

Property Value

Remarks

KeyCollector

Property Value

Remarks

Methods

AddPermissions(PinUvAuthTokenPermissions, string?)

Parameters

Remarks

Exceptions

ChangePin()

Remarks

Exceptions

ClearAuthToken()

Remarks

DeleteCredential(CredentialId)

Parameters

Remarks

Exceptions

Dispose()

EnrollFingerprint(string?, int?)

Parameters

Returns

Remarks

Exceptions

EnumerateBioEnrollments()

Returns

Remarks

Exceptions

EnumerateCredentialsForRelyingParty(RelyingParty)

Parameters

Returns

Remarks

Exceptions

EnumerateRelyingParties()

Returns

Remarks

Exceptions

GetAssertions(GetAssertionParameters)

Note

Parameters

Returns

Remarks

Exceptions

GetBioModality()

Returns

Remarks

GetCredentialMetadata()

Returns

Remarks

Exceptions

GetFingerprintSensorInfo()

Returns

Remarks

Exceptions