U2fSession Class

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

Name	Description
U2fSession(IYubiKeyDevice)	Creates an instance of U2fSession, the object that represents the FIDO U2F application on the YubiKey.

Properties

Name	Description
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.
KeyCollector	A callback that this class will call when it needs the YubiKey touched or a PIN to be verified.

Methods

Name	Description
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.
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.
Dispose()
EncodeAndHashString(string)	Helper function that takes a string and computes the SHA-256 hash of the UTF-8 encoding.
Register(ReadOnlyMemory<byte>, ReadOnlyMemory<byte>, TimeSpan)	Registers a new U2F credential onto the authenticator (the YubiKey).
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.
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.
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`.
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`.
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.
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`.
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`.
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`.
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`.
VerifyKeyHandle(ReadOnlyMemory<byte>, ReadOnlyMemory<byte>, ReadOnlyMemory<byte>)	Verify that the given `keyHandle` is a YubiKey handle and matches the `applicationId` and `clientDataHash`.
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.