Class U2fSession

Namespace: Yubico.YubiKey.U2f

Assembly: Yubico.YubiKey.dll

Represents an active session to the FIDO U2F application on the YubiKey.

public sealed class U2fSession

Inheritance: object

U2fSession

Remarks

When you need to perform FIDO U2F 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 U2fSession class to represent the U2F application on the hardware. Because this class implements IDisposable, use the using keyword. For example,

IYubiKeyDevice yubiKeyToUse = SelectYubiKey();
using (var u2f = new U2fSession(yubiKeyToUse))
{
    /* Perform FIDO U2F 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 the active U2F session. This will clear any application state, and ultimately release the connection to the YubiKey.

Constructors

U2fSession(IYubiKeyDevice)

Creates an instance of U2fSession, the object that represents the FIDO U2F application on the YubiKey.

public U2fSession(IYubiKeyDevice yubiKey)

Parameters

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

Remarks

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

IYubiKeyDevice yubiKeyToUse = SelectYubiKey();
using (var u2f = new U2fSession(yubiKeyToUse))
{
    /* Perform U2F operations. */
}

Exceptions

ArgumentNullException: The yubiKey argument is null.

Properties

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

KeyCollector

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

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

Property Value

Func<KeyEntryData, bool>

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.

Methods

Authenticate(ReadOnlyMemory<byte>, ReadOnlyMemory<byte>, ReadOnlyMemory<byte>, TimeSpan, bool)

Authenticates a credential. Throw an exception if the method is not able to perform the operation.

public AuthenticationData Authenticate(ReadOnlyMemory<byte> applicationId, ReadOnlyMemory<byte> clientDataHash, ReadOnlyMemory<byte> keyHandle, TimeSpan timeout, bool requireProofOfPresence = true)

Parameters

applicationId ReadOnlyMemory<byte>: Also known as the origin data. A SHA-256 hash of the UTF-8 encoding of the application or service requesting the authentication. See the user's manual article on How Fido U2F works for more information.
clientDataHash ReadOnlyMemory<byte>: A SHA-256 hash of the client data, a stringified JSON data structure that the caller prepares. Among other things, the client data contains the challenge from the relying party (the application or service that this registration is for). See the user's manual article on How Fido U2F works for more information.
keyHandle ReadOnlyMemory<byte>: The key handle the YubiKey returned during registration. That value was sent to the relying party and now is being returned to the YubiKey (via the client).
timeout TimeSpan: The amount of time this method will wait for user touch. The recommended timeout is 5 seconds. The minimum is 1 second and the maximum is 30 seconds. If the input is greater than 30 seconds, this method will set the timeout to 30. If the timeout is greater than 0 but less than one second, the method will set the timeout to 1 second. If the timeout is zero, this method will set no timeout and wait for touch indefinitely (zero timeout means no timeout).
requireProofOfPresence bool: If true, then the user must provide proof of presence in order to complete the authentication. If false, proof of presence is not necessary. The default is true so if no value is given for this argument, it will be true. With the YubiKey proof of user presence is touch.

Returns

AuthenticationData: A structure containing the results of the credential authentication, including the signature.

Remarks

The client gets the key handle along with the challenge from the relying party, and computes the application ID (origin data) and the client data hash using the challenge. The client then sends the relevant data to the YubiKey. If the YubiKey can build a private key from the key handle, it will sign the appId and client data hash. This is how the YubiKey authenticates to the relying party.

The YubiKey will also be able to use the key handle to verify it is talking to a relying party with which it is registered. If the key handle can be "converted" into an actual key matching the origin data, then the YubiKey will compute a signature. If not, the YubiKey will reject the key handle and this method will throw an exception (with the message "The request was rejected due to an invalid key handle.").

The application ID is a SHA-256 hash of the UTF-8 encoding of the application or service (the relying party) requesting the registration. This is also known as the origin data. For a website, this is typically the https address of the primary domain, not including the final slash. For example, https://fido.example.com/myApp. If there are multiple addresses than can be associated with this credential, the application ID should refer to a single trusted facet list. This is a JSON structure that contains a list of URI / IDs that the client should accept.

Non-websites may use FIDO U2F. Therefore their applicationId will most likely not be a URL. Android and iOS have their own special encodings based on their application package metadata. Clients on Linux, macOS, and Windows have fewer guidelines and can usually be defined by the application. See the How FIDO U2f works page in the user's manual for more information.

The U2F standard specifies that a client can call on the token to authenticate and require proof of user presence or not. That is, the client can ask the token to authenticate directly with no further user interaction. This argument is true by default, meaning proof of presence is required. With the YubiKey, proof of user presence is touch. Note that if this argument is false, then this method will ignore the timeout argument.

A version 4 FIPS YubiKey can have a PIN set on the U2F application. That PIN applies to registration only. A PIN is never needed to perform authentication.

Exceptions

TimeoutException: The user presence check timed out.
InvalidOperationException: The input data was invalid (e.g. the appId was not 32 bytes) or else the key handle was not correct for the appId.

ChangePin()

For a version 4 FIPS series YubiKey that has a PIN set on the U2F application, this will call on the KeyCollector to obtain the current and a new PIN and use them to change the U2F PIN.

public void ChangePin()

Remarks

A version 4 FIPS series YubiKey is manufactured with no PIN set on the U2F application. At this point, the YubiKey is not in FIPS mode. Once the PIN is set, it is in FIPS mode See SetPin(). After it has been set, it is possible to change the PIN to a new value.

Once a PIN is set, however, the only way to remove a PIN is to reset the entire U2F application. After reset, the YubiKey's U2F application is no longer in FIPS mode, and furthermore, it can never be put into FIPS mode again. It can be set with a PIN again, but that will not put a reset YubiKey into FIPS mode.

The current PIN must be entered, even if the PIN has been verified in the current session. If the wrong current PIN is entered, the YubiKey will decrement the retries remaining count, and this method will call on the KeyCollector for the current and new PIN again (the KeyEntryData.IsRetry property will be true). See the user's manual entry on FIDO U2F FIPS mode retries for more information.

The PIN is binary data and must be at least 6 and no more than 32 bytes long. If the user enters a value too short or too long, this method will not change the PIN, but it will call the KeyCollector again requesting the user enter a new PIN.

While the PIN can be any binary value, most PINs will be letters, numbers, and other characters entered from a keyboard. It is the responsibility of the app to determine how a character typed at a keyboard is represented as a byte. Almost certainly the best encoding will be UTF-8. In UTF-8, each ASCII character ie encoded with the single byte that is the ASCII character. For example, the character "5" in ASCII is 0x35. In UTF-8, it is 0x35. The character "C" is 0x43 in both ASCII and UTF-8.

Note that if the SDK calls the KeyCollector to try again, it will not specify what the problem is, wrong current PIN or invalid new PIN. Hence, it would be a good idea if your KeyCollector checked the length of the new PIN and reject it before passing it on to the SDK. If so, then you know a retry means incorrect current PIN.

Note that a PIN is needed to perform U2F registration, but not authentication.

Exceptions

SecurityException: The YubiKey is not version 4 FIPS series, or the PIN is blocked.
OperationCanceledException: The user cancelled. This happens when this method calls the KeyCollector and it returns false.

Dispose()

public void Dispose()

EncodeAndHashString(string)

Helper function that takes a string and computes the SHA-256 hash of the UTF-8 encoding.

public static byte[] EncodeAndHashString(string data)

Parameters

data string: The string to encode.

Returns

byte[]: The SHA-256 hash of the string encoded as UTF-8.

Remarks

Use this helper function to simplify calling other U2F functions such as Register(ReadOnlyMemory<byte>, ReadOnlyMemory<byte>, TimeSpan) and Authenticate. This function will take the provided string, encode it into a byte array using the UTF-8 encoding style, and then pass those bytes into a SHA256 hash function. This transformation can be used for things like the applicationId and the clientDataHash.

This function uses the SHA256 cryptographic function. By default, this will rely on the implementation provided by the .NET base class library. If you wish to override this implementation with your own, you can do so by setting a SHA256 creator on the CryptographyProviders class. See the User's manual page on providing alternate cryptographic implementations for more information.

Register(ReadOnlyMemory<byte>, ReadOnlyMemory<byte>, TimeSpan)

Registers a new U2F credential onto the authenticator (the YubiKey).

public RegistrationData Register(ReadOnlyMemory<byte> applicationId, ReadOnlyMemory<byte> clientDataHash, TimeSpan timeout)

Parameters

applicationId ReadOnlyMemory<byte>: Also known as the origin data. A SHA-256 hash of the UTF-8 encoding of the application or service requesting the registration. See the U2F registration overview page for more information.
clientDataHash ReadOnlyMemory<byte>: A SHA-256 hash of the client data, a stringified JSON data structure that the caller prepares. Among other things, the client data contains the challenge from the relying party (the application or service that this registration is for). See the U2F registration overview page for more information.
timeout TimeSpan: The amount of time this method will wait for user touch. The recommended timeout is 5 seconds. The minimum is 1 second and the maximum is 30 seconds. If the input is greater than 30 seconds, this method will set the timeout to 30. If the timeout is greater than 0 but less than one second, the method will set the timeout to 1 second. If the timeout is zero, this method will set no timeout and wait for touch indefinitely (zero timeout means no timeout).

Returns

RegistrationData: A structure containing the results of the credential registration, including the user public key, key handle, attestation certificate, and the signature.

Remarks

The application ID is a SHA-256 hash of the UTF-8 encoding of the application or service (the relying party) requesting the registration. For a website, this is typically the https address of the primary domain, not including the final slash. For example https://fido.example.com/myApp. If there are multiple addresses that can be associated with this credential, the application ID should refer to a single trusted facet list. This is a JSON structure that contains a list of URI / IDs that the client should accept.

Non-websites may use FIDO U2F. Therefore their applicationId (origin data) will most likely not be a URL. Android and iOS have their own special encodings based on their application package metadata. Clients on Linux, macOS, and Windows have fewer guidelines and can usually be defined by the application. See the U2F registration overview page for more information.

The client data hash is a SHA-256 hash of the UTF-8 encoding of a JSON data structure that the app calling this API (the client) must prepare. It consists of: a typ field that must be set to navigator.id.finishEnrollment, a challenge field that is a websafe-base64-encoded challenge provided by the relying party, an origin field that is the exact facet id (the website or identifier) used by the relying party, an optional cid_pubkey field that represents the channel ID public key used by this app to communicate with the above origin.

The results of the registration should be sent back to the relying party service for verification. This includes the P-256 NIST elliptic curve public key that represents this credential, a key handle that acts as an identifier for the generated key pair, an attestation certificate of the authenticator (the YubiKey), and a signature of the challenge (and other data).

The signature must be verified by the relying party using the public key certified in the attestation statement. The relying party should also validate that the attestation certificate chains up to a trusted certificate authority. Once the relying party verifies the signature, it should store the public key and key handle for future authentication operations.

The YubiKey will not compute a signature (complete the registration) without proof of user presence. That means the user must touch the YubiKey's sensor. When this method gets to the point that the touch is needed before it can continue, it will call the KeyCollector with the Request> of TouchRequest. At that point, the calling app can display a message (e.g. launch a window) indicating the user needs to touch the YubiKey to complete the operation. When the Registration is complete (or upon an error or timeout), the SDK will call the KeyCollector with the Request of Release, meaning the calling app now knows it can take away the touch request message.

The YubiKey extends the FIDO U2F spec with its YubiKey 4 FIPS series of devices with the addition of a PIN. This PIN is required to modify the FIDO U2F application, including the registration of new U2F credentials. Applications that intend to interoperate with YubiKey FIPS devices should implement a KeyCollector so that a PIN can be collected and verified when required. If no KeyCollector is provided, then the calling app should call the method that directly verifies the PIN.

Exceptions

TimeoutException: The user presence check timed out.
InvalidOperationException: The input data was invalid (e.g. the appId was not 32 bytes) or else the YubiKey was version 4 FIPS in FIPS mode, and needed the PIN verified. However, it was not verified and there was no KeyCollector.
OperationCanceledException: The YubiKey was version 4 FIPS in FIPS mode, and needed the PIN verified. However, it was not verified and the user canceled PIN collection.
SecurityException: The YubiKey was version 4 FIPS in FIPS mode, and needed the PIN verified. However, it was not verified and the PIN was blocked (no more retries remaining).

SetPin()

For a version 4 FIPS series YubiKey that does not have a PIN set, this will call on the KeyCollector to obtain a PIN and use it to set the U2F application with that PIN.

public void SetPin()

Remarks

A version 4 FIPS series YubiKey is manufactured with no PIN set on the U2F application. At this point, the YubiKey is not in FIPS mode. Once the PIN is set, it is in FIPS mode.

Once a PIN is set, it is possible to change it (see ChangePin()), however, the only way to remove a PIN is to reset the entire U2F application. After reset, the YubiKey's U2F application is no longer in FIPS mode, and furthermore, it can never be put into FIPS mode again. It can be set with a PIN again, but that will not put a reset YubiKey into FIPS mode.

The PIN is binary data and must be at least 6 and no more than 32 bytes long. If the user enters a value too short or too long, this method will not set the PIN, but it will call the KeyCollector again requesting the user enter a new PIN.

Note that a PIN is needed to perform U2F registration, but not authentication.

Exceptions

SecurityException: The YubiKey is not version 4 FIPS series, or the U2F application is already set with a PIN, or the PIN is blocked.
OperationCanceledException: The user cancelled. This happens when this method calls the KeyCollector and it returns false.

TryAuthenticate(ReadOnlyMemory<byte>, ReadOnlyMemory<byte>, ReadOnlyMemory<byte>, TimeSpan, out AuthenticationData, bool)

Try to authenticate a credential. If this method can't authenticate the input data or compute the signature, return false. Any other error will throw an exception.

public bool TryAuthenticate(ReadOnlyMemory<byte> applicationId, ReadOnlyMemory<byte> clientDataHash, ReadOnlyMemory<byte> keyHandle, TimeSpan timeout, out AuthenticationData authenticationData, bool requireProofOfPresence = true)

Parameters

applicationId ReadOnlyMemory<byte>: Also known as the origin data. A SHA-256 hash of the UTF-8 encoding of the application or service requesting the authentication. See the user's manual article on How Fido U2F works for more information.
clientDataHash ReadOnlyMemory<byte>: A SHA-256 hash of the client data, a stringified JSON data structure that the caller prepares. Among other things, the client data contains the challenge from the relying party (the application or service that this registration is for). See the user's manual article on How Fido U2F works for more information.
keyHandle ReadOnlyMemory<byte>: The key handle the YubiKey returned during registration. That value was sent to the relying party and now is being returned to the YubiKey (via the client).
timeout TimeSpan: The amount of time this method will wait for user touch. The recommended timeout is 5 seconds. The minimum is 1 second and the maximum is 30 seconds. If the input is greater than 30 seconds, this method will set the timeout to 30. If the timeout is greater than 0 but less than one second, the method will set the timeout to 1 second. If the timeout is zero, this method will set no timeout and wait for touch indefinitely (zero timeout means no timeout).
authenticationData AuthenticationData: A structure containing the results of the credential authentication, including the signature.
requireProofOfPresence bool: If true, then the user must provide proof of presence in order to complete the authentication. If false, proof of presence is not necessary. The default is true so if no value is given for this argument, it will be true. With the YubiKey proof of user presence is touch.

Returns

bool: true when the credential was successfully authenticated, false when the input data could not be used, such as a key handle that did not match the appId.

Remarks

See the comments for Authenticate(ReadOnlyMemory<byte>, ReadOnlyMemory<byte>, ReadOnlyMemory<byte>, TimeSpan, bool) as they apply to this method as well.

Exceptions

TimeoutException: The user presence check timed out.

TryChangePin()

For a version 4 FIPS series YubiKey that has a PIN set on the U2F application, this will call on the KeyCollector to obtain the current and a new PIN and use them to change the U2F PIN. If the caller cancels (the return from the KeyCollector is false), this will return false.

public bool TryChangePin()

Returns

bool: A boolean, true if the PIN is changed, false if the user cancels PIN collection.

Remarks

See the documentation for ChangePin() for more information on changing a PIN.

Exceptions

SecurityException: The YubiKey is not version 4 FIPS series, or the PIN is blocked.

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

For a version 4 FIPS series YubiKey that has a PIN set on the U2F application, this will use the provided current and new PINs to change the U2F PIN. If the current PIN given is not correct, or the new PIN is not a correct length, this method will return false.

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

Parameters

currentPin ReadOnlyMemory<byte>
newPin ReadOnlyMemory<byte>

Returns

bool: A boolean, true if the PIN is changed, false otherwise.

Remarks

See the documentation for ChangePin() for more information on changing a PIN.

Exceptions

SecurityException: The PIN is blocked.
NotSupportedException: The YubiKey is not version 4 FIPS series.

TryRegister(ReadOnlyMemory<byte>, ReadOnlyMemory<byte>, TimeSpan, out RegistrationData)

Attempts to register a new U2F credential onto the authenticator (the YubiKey). This will return false if the user cancels PIN collection (FIPS series 4 YubiKey in FIPS mode only) or if there is some other error, such as bad application ID data.

public bool TryRegister(ReadOnlyMemory<byte> applicationId, ReadOnlyMemory<byte> clientDataHash, TimeSpan timeout, out RegistrationData registrationData)

Parameters

applicationId ReadOnlyMemory<byte>: Also known as the origin data. A SHA-256 hash of the UTF-8 encoding of the application or service requesting the registration. See the U2F registration overview page for more information.
clientDataHash ReadOnlyMemory<byte>: A SHA-256 hash of the client data, a stringified JSON data structure that the caller prepares. Among other things, the client data contains the challenge from the relying party (the application or service that this registration is for). See the U2F registration overview page for more information.
timeout TimeSpan: The amount of time this method will wait for user touch. The recommended timeout is 5 seconds. The minimum is 1 second and the maximum is 30 seconds. If the input is greater than 30 seconds, this method will set the timeout to 30. If the timeout is greater than 0 but less than one second, the method will set the timeout to 1 second. If the timeout is zero, this method will set no timeout and wait for touch indefinitely (zero timeout means no timeout).
registrationData RegistrationData: A structure containing the results of the credential registration, including the user public key, key handle, attestation certificate, and the signature.

Returns

bool: true when the credential was successfully registered, false when the input data was not correct or the user canceled PIN collection.

Remarks

The YubiKey extends the FIDO U2F spec with its YubiKey 4 FIPS series of devices with the addition of a PIN. This PIN is required to modify the FIDO U2F application, including the registration of new U2F credentials. Applications that intend to interoperate with YubiKey FIPS devices should implement a KeyCollector so that a PIN can be collected and verified when required. The alternative is to call the TryVerifyPin() method at the beginning of the session. In that case, no KeyCollector will be necessary.

Exceptions

TimeoutException: The user presence check timed out.
InvalidOperationException: The YubiKey was version 4 FIPS in FIPS mode, and needed the PIN verified. However, it was not verified and there was no KeyCollector.
SecurityException: The YubiKey was version 4 FIPS in FIPS mode, and needed the PIN verified. However, it was not verified and the PIN was blocked (no more retries remaining).

TrySetPin()

For a version 4 FIPS series YubiKey that does not have a PIN set, this will call on the KeyCollector to obtain a PIN and use it to set the U2F application with that PIN. If the caller cancels (the return from the KeyCollector is false), this will return false.

public bool TrySetPin()

Returns

bool: A boolean, true if the PIN is set, false if the user cancels PIN collection.

Remarks

See the documentation for SetPin() for more information on setting a PIN.

Exceptions

SecurityException: The YubiKey is not version 4 FIPS series, or the U2F application is already set with a PIN, or the PIN is blocked.

TrySetPin(ReadOnlyMemory<byte>)

For a version 4 FIPS series YubiKey that does not have a PIN set, this will try to set the PIN using the given pin.

public bool TrySetPin(ReadOnlyMemory<byte> pin)

Parameters

pin ReadOnlyMemory<byte>

Returns

bool: A boolean, true if the PIN is set, false if the user cancels PIN collection.

Remarks

See the documentation for SetPin() for more information on setting a PIN.

If the input pin is less than 6 or more than 32 bytes long, this method will return false. However, this method will throw an exception if the U2F application is already set, the PIN is blocked, or the YubiKey is not version 4 FIPS series.

Exceptions

SecurityException: The U2F application is already set with a PIN, or the PIN is blocked.
NotSupportedException: The YubiKey is not version 4 FIPS series.

TryVerifyPin()

For a version 4 FIPS series YubiKey that has a PIN set on the U2F application, this will call on the KeyCollector to obtain the current PIN and verify it. If the caller cancels (the return from the KeyCollector is false), this will return false.

public bool TryVerifyPin()

Returns

bool: A boolean, true if the PIN is verified, false if the user cancels PIN collection.

Remarks

See the documentation for VerifyPin() for more information on verifying a PIN.

Exceptions

SecurityException: The YubiKey is not version 4 FIPS series, or the PIN is blocked.

TryVerifyPin(ReadOnlyMemory<byte>)

For a version 4 FIPS series YubiKey that has a PIN set on the U2F application, this try to verify the given pin. If the PIN is not verified, this method will return false.

public bool TryVerifyPin(ReadOnlyMemory<byte> pin)

Parameters

pin ReadOnlyMemory<byte>

Returns

bool: A boolean, true if the PIN is verified, false otherwise.

Remarks

See the documentation for VerifyPin() for more information on verifying a PIN.

Exceptions

SecurityException: The PIN is blocked.
NotSupportedException: The YubiKey is not version 4 FIPS series.

VerifyKeyHandle(ReadOnlyMemory<byte>, ReadOnlyMemory<byte>, ReadOnlyMemory<byte>)

Verify that the given keyHandle is a YubiKey handle and matches the applicationId and clientDataHash.

public bool VerifyKeyHandle(ReadOnlyMemory<byte> applicationId, ReadOnlyMemory<byte> clientDataHash, ReadOnlyMemory<byte> keyHandle)

Parameters

applicationId ReadOnlyMemory<byte>: Also known as the origin data. A SHA-256 hash of the UTF-8 encoding of the application or service requesting the registration. See the U2F registration overview page for more information.
clientDataHash ReadOnlyMemory<byte>: A SHA-256 hash of the client data, a stringified JSON data structure that the caller prepares. Among other things, the client data contains the challenge from the relying party (the application or service that this verification is for). See the U2F registration overview page for more information.
keyHandle ReadOnlyMemory<byte>: The key handle the provided by the relying party.

Returns

bool: A boolean, true if the key handle matches, false otherwise.

Remarks

When performing an authentication, the relying party sends the key handle that the YubiKey should use to sign the challenge. The client passes that key handle along to the YubiKey, along with the applicationID (origin data) and client data hash. The YubiKey will determine if the key handle is valid and if so, if it matches the origin data. If it does, the YubiKey will sign the challenge and if not, the YubiKey will simply not create a signature. This is the YubiKey verifying the relying party.

Call this method to check the key handle before trying to execute a full authentication operation. This operation is specified by the U2F standard.

Note that there are three primary ways this method will return false. One, the key handle does not belong to the YubiKey, two, the key handle does not match the applicationID (origin data), and three, the data is invalid (e.g. a 16-byte client data hash).

VerifyPin()

For a version 4 FIPS series YubiKey that has a PIN set on the U2F application, this will call on the KeyCollector to obtain the current PIN and verify it.

public void VerifyPin()

Remarks

Note that if the PIN is not verified and the Register(ReadOnlyMemory<byte>, ReadOnlyMemory<byte>, TimeSpan) method is called, the SDK will call this Verify method. Hence, it is likely an app will never need to call this method directly.

If the wrong current PIN is entered, the YubiKey will decrement the retries remaining count, and this method will call on the KeyCollector for the current PIN again (the KeyEntryData.IsRetry property will be true). See the user's manual entry on FIDO U2F FIPS mode retries for more information.

The PIN is binary data and must be at least 6 and no more than 32 bytes long. If the user enters a value too short or too long, this method will try to verify that value, the YubiKey will reject it, and this method will call the KeyCollector again requesting the user enter the PIN.

Exceptions

SecurityException: The YubiKey is not version 4 FIPS series, or the PIN is blocked.
OperationCanceledException: The user cancelled. This happens when this method calls the KeyCollector and it returns false.

Table of Contents

Class U2fSession

Remarks

Constructors

U2fSession(IYubiKeyDevice)

Parameters

Remarks

Exceptions

Properties

Connection

Property Value

KeyCollector

Property Value

Remarks

Methods

Authenticate(ReadOnlyMemory<byte>, ReadOnlyMemory<byte>, ReadOnlyMemory<byte>, TimeSpan, bool)

Parameters

Returns

Remarks

Exceptions

ChangePin()

Remarks

Exceptions

Dispose()

EncodeAndHashString(string)

Parameters

Returns

Remarks

Register(ReadOnlyMemory<byte>, ReadOnlyMemory<byte>, TimeSpan)

Parameters

Returns

Remarks

Exceptions

SetPin()

Remarks

Exceptions

TryAuthenticate(ReadOnlyMemory<byte>, ReadOnlyMemory<byte>, ReadOnlyMemory<byte>, TimeSpan, out AuthenticationData, bool)

Parameters

Returns

Remarks

Exceptions

TryChangePin()

Returns

Remarks

Exceptions

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

Parameters

Returns

Remarks

Exceptions

TryRegister(ReadOnlyMemory<byte>, ReadOnlyMemory<byte>, TimeSpan, out RegistrationData)

Parameters

Returns

Remarks

Exceptions

TrySetPin()

Returns

Remarks

Exceptions

TrySetPin(ReadOnlyMemory<byte>)

Parameters

Returns

Remarks

Exceptions

TryVerifyPin()

Returns

Remarks

Exceptions

TryVerifyPin(ReadOnlyMemory<byte>)

Parameters

Returns

Remarks

Exceptions

VerifyKeyHandle(ReadOnlyMemory<byte>, ReadOnlyMemory<byte>, ReadOnlyMemory<byte>)

Parameters

Returns

Remarks

VerifyPin()

Remarks

Exceptions