Table of Contents

Class YubiKeyDevice

Namespace
Yubico.YubiKey
Assembly
Yubico.YubiKey.dll

Provides device and enumeration capabilities.

public class YubiKeyDevice : IYubiKeyDevice, IYubiKeyDeviceInfo
Inheritance
object
YubiKeyDevice
Implements
Extension Methods

Constructors

YubiKeyDevice(IDevice, IYubiKeyDeviceInfo)

Constructs a YubiKeyDevice instance.

public YubiKeyDevice(IDevice device, IYubiKeyDeviceInfo info)

Parameters

device IDevice

A valid device; either a smart card, keyboard, or FIDO device.

info IYubiKeyDeviceInfo

The YubiKey device information that describes the device.

Exceptions

ArgumentException

An unrecognized device type was given.

YubiKeyDevice(ISmartCardDevice?, IHidDevice?, IHidDevice?, IYubiKeyDeviceInfo)

Construct a YubiKeyDevice instance.

public YubiKeyDevice(ISmartCardDevice? smartCardDevice, IHidDevice? hidKeyboardDevice, IHidDevice? hidFidoDevice, IYubiKeyDeviceInfo yubiKeyDeviceInfo)

Parameters

smartCardDevice ISmartCardDevice

ISmartCardDevice for the YubiKey.

hidKeyboardDevice IHidDevice

IHidDevice for normal HID interaction with the YubiKey.

hidFidoDevice IHidDevice

IHidDevice for FIDO interaction with the YubiKey.

yubiKeyDeviceInfo IYubiKeyDeviceInfo

IYubiKeyDeviceInfo with remaining properties of the YubiKey.

Properties

AutoEjectTimeout

The CCID auto-eject timeout (in seconds).

public int AutoEjectTimeout { get; }

Property Value

int

Remarks

This field is only meaningful if TouchEject in DeviceFlags is set. A value of 0 means that the timeout is disabled (the smart card will not be ejected automatically).

The range is ushort.MinValue through ushort.MaxValue.

AvailableNfcCapabilities

The paid-for YubiKey features that are available over NFC.

public YubiKeyCapabilities AvailableNfcCapabilities { get; }

Property Value

YubiKeyCapabilities

AvailableTransports

Indicates which logical device transports are available to this YubiKey device.

public Transport AvailableTransports { get; }

Property Value

Transport

Remarks

A YubiKey can be connected to a computer in multiple ways: physically connected via USB or Lightning, or by being present in an NFC reader's field. Further, when connected through USB, the YubiKey appears to the computer as multiple devices. It can look like a HID Keyboard, a HID FIDO device, and a smart card reader. This property shows which of these connections are present.

For example: if this YubiKey instance is connected through an NFC reader, this value will be NfcSmartCard. If it is connected through USB and all of the three USB interfaces are available, it will contain the set HidKeyboard, HidFido, and UsbSmartCard.

AvailableUsbCapabilities

The paid-for YubiKey features that are available over USB (and Lightning).

public YubiKeyCapabilities AvailableUsbCapabilities { get; }

Property Value

YubiKeyCapabilities

ChallengeResponseTimeout

The period of time (in seconds) after which the OTP challenge-response command should timeout.

public byte ChallengeResponseTimeout { get; }

Property Value

byte

Remarks

The default value for the timeout is 15 seconds.

ConfigurationLocked

Indicates whether or not the YubiKey's configuration has been locked by the user.

public bool ConfigurationLocked { get; }

Property Value

bool

DeviceFlags

Device flags that can control device-global behavior.

public DeviceFlags DeviceFlags { get; }

Property Value

DeviceFlags

EnabledNfcCapabilities

The NFC features that are currently enabled over NFC.

public YubiKeyCapabilities EnabledNfcCapabilities { get; }

Property Value

YubiKeyCapabilities

EnabledUsbCapabilities

The USB features that are currently enabled over USB (and Lightning).

public YubiKeyCapabilities EnabledUsbCapabilities { get; }

Property Value

YubiKeyCapabilities

FipsApproved

The set of YubiKey applications that are currently configured to meet FIPS requirements.

public YubiKeyCapabilities FipsApproved { get; }

Property Value

YubiKeyCapabilities

FipsCapable

The set of YubiKey applications that are capable of being put into FIPS mode.

public YubiKeyCapabilities FipsCapable { get; }

Property Value

YubiKeyCapabilities

FirmwareVersion

The version of the firmware currently running on the YubiKey.

public FirmwareVersion FirmwareVersion { get; }

Property Value

FirmwareVersion

FormFactor

The form-factor of the YubiKey.

public FormFactor FormFactor { get; }

Property Value

FormFactor

ImageProcessorVersion

The version of the chip/firmware performing the image processing. If there is no image processing chip, this will be null. This field is also known as the "STM Version".

public ImageProcessorVersion? ImageProcessorVersion { get; }

Property Value

ImageProcessorVersion

IsFipsSeries

Indicates whether or not the YubiKey is a FIPS Series device.

public bool IsFipsSeries { get; }

Property Value

bool

Remarks

When using a YubiKey FIPS Series device as an authenticator in a FIPS environment, all of the sub-modules must be in a FIPS approved mode of operation for the YubiKey FIPS Series device as a whole to be considered as operating in a FIPS approved mode. This value does not determine whether the YubiKey is in a FIPS approved mode.

IsNfcRestricted

Indicates if the NFC connectivity on the device is temporarily disabled

public bool IsNfcRestricted { get; }

Property Value

bool

IsPinComplexityEnabled

Whether or not pin complexity is enabled on the Yubikey. For more information see this documentation on pin complexity

public bool IsPinComplexityEnabled { get; }

Property Value

bool

IsSkySeries

Indicates whether or not this device is a "Security Key by Yubico" series device.

public bool IsSkySeries { get; }

Property Value

bool

Remarks

Security Key Series devices only support the U2F and FIDO2 applications. This property helps differentiate these devices from a standard YubiKey that only has these two applications enabled.

PartNumber

The part number for the Secure Element processor, if available, otherwise null

public string? PartNumber { get; }

Property Value

string

ResetBlocked

The set of YubiKey applications that are blocked from being reset.

public YubiKeyCapabilities ResetBlocked { get; }

Property Value

YubiKeyCapabilities

SerialNumber

The serial number of the YubiKey, if one is present. Security Keys don't have serial numbers

public int? SerialNumber { get; }

Property Value

int?

TemplateStorageVersion

The version of the chip/firmware storing the fingerprints (the second secure element). If there is no template storage chip, this will be null. This field is also known as the "FPS Version".

public TemplateStorageVersion? TemplateStorageVersion { get; }

Property Value

TemplateStorageVersion

Methods

CompareTo(IYubiKeyDevice) 

public int CompareTo(IYubiKeyDevice other)

Parameters

other IYubiKeyDevice

Returns

int

Connect(byte[])

Initiate a connection to the specified application represented as an applicationId on a YubiKey device.

public IYubiKeyConnection Connect(byte[] applicationId)

Parameters

applicationId byte[]

A byte array representing the smart card Application ID (AID) for the application to open.

Returns

IYubiKeyConnection

An instance of a class that implements the IYubiKeyConnection interface.

Connect(byte[], ScpKeyParameters)

Initiate a connection to the specified application on a YubiKey device using SCP protocol.

public virtual IScpYubiKeyConnection Connect(byte[] applicationId, ScpKeyParameters keyParameters)

Parameters

applicationId byte[]

A byte array representing the smart card Application ID (AID) for the application to open.

keyParameters ScpKeyParameters

The SCP key parameters to use in making an SCP connection.

Returns

IScpYubiKeyConnection

An instance of a class that implements the IScpYubiKeyConnection interface.

Remarks

Note that SCP works only with SmartCard applications, namely PIV, OATH, OTP, Security Domain and YubiHsmAuth and OpenPgp. However, SCP03 is supported only on series 5 YubiKeys with firmware version on 5.3 and above. SCP 11 is supported only firmware version 5.7.2 and above.

Note also that the return is an instance of a class that implements IScpYubiKeyConnection which is a "subclass" of IYubiKeyConnection.

Connect(YubiKeyApplication)

Initiate a connection to the specified application on a YubiKey device.

public virtual IYubiKeyConnection Connect(YubiKeyApplication application)

Parameters

application YubiKeyApplication

The application to reference on the device.

Returns

IYubiKeyConnection

An instance of a class that implements the IYubiKeyConnection interface.

Connect(YubiKeyApplication, ScpKeyParameters)

Initiate a connection to the specified application on a YubiKey device using SCP protocol.

public virtual IScpYubiKeyConnection Connect(YubiKeyApplication application, ScpKeyParameters keyParameters)

Parameters

application YubiKeyApplication

The YubiKeyApplication to reference on the device.

keyParameters ScpKeyParameters

The SCP key parameters to use in making an SCP connection.

Returns

IScpYubiKeyConnection

An instance of a class that implements the IScpYubiKeyConnection interface.

Remarks

Note that SCP works only with SmartCard applications, namely PIV, OATH, OTP, Security Domain and YubiHsmAuth and OpenPgp. However, SCP03 is supported only on series 5 YubiKeys with firmware version on 5.3 and above. SCP 11 is supported only firmware version 5.7.2 and above.

Note also that the return is an instance of a class that implements IScpYubiKeyConnection which is a "subclass" of IYubiKeyConnection.

Contains(IDevice) 

protected bool Contains(IDevice other)

Parameters

other IDevice

Returns

bool

DeviceReset()

Perform a device-wide factory reset on a YubiKey Bio Multi-protocol Edition key.

public void DeviceReset()

Remarks

Resets ALL YubiKey applications (including FIDO and PIV) on the key to factory settings. This type of reset is only available on YubiKey Bio Multi-protocol Edition keys.

A reset will delete all FIDO2 credentials, fingerprints, and associated information, remove the shared PIN, delete all PIV keys and certificates from PIV slots (except the F9 attestation slot), remove any information added to the PIV data elements, and set the PIV PUK and management key back to their factory default states.

Exceptions

NotSupportedException

The YubiKey does not support this feature.

InvalidOperationException

The YubiKey encountered an error and could not set the setting.

Equals(object) 

public override bool Equals(object obj)

Parameters

obj object

Returns

bool

Equals(IYubiKeyDevice) 

public bool Equals(IYubiKeyDevice other)

Parameters

other IYubiKeyDevice

Returns

bool

FindAll()

Enumerate all YubiKeys on the system over all available transports.

public static IEnumerable<IYubiKeyDevice> FindAll()

Returns

IEnumerable<IYubiKeyDevice>

A collection of YubiKeys that were found, as IYubiKeyDevices.

Remarks

This method will exclude any connection (SmartCard, HidFido, HidKeyboard) that did not successfully respond to a request for its Firmware Version. This means that there may be fewer IYubiKeys returned than expected, or that some IYubiKeys are missing an expected connection.

To the host device, a single YubiKey can appear as multiple devices. This method will attempt to match these devices back together into a single IYubiKeyDevice using their serial number. If they cannot be matched, each connection will be returned as a separate IYubiKeyDevice.

If your application no longer needs to watch for insertion or removal notifications, you can call StopListening() to release resources and avoid the logging and other actions from the listeners.

FindByTransport(Transport)

Enumerate YubiKeys over the given transports.

public static IEnumerable<IYubiKeyDevice> FindByTransport(Transport transport = Transport.All)

Parameters

transport Transport

Argument controls which devices are searched for. Values None will result in exceptions being thrown. FindAll() is a convenience function to find All.

Returns

IEnumerable<IYubiKeyDevice>

A collection of YubiKeys that were found, as IYubiKeyDevices.

Remarks

This method will exclude any connection (SmartCard, HidFido, HidKeyboard) that did not successfully respond to a request for its Firmware Version. This means that there may be fewer IYubiKeys returned than expected, or that some IYubiKeys are missing an expected connection.

To the host device, a single YubiKey can appear as multiple devices. This method will attempt to match these devices back together into a single IYubiKeyDevice using their serial number. If they cannot be matched, each connection will be returned as a separate IYubiKeyDevice.

If your application no longer needs to watch for insertion or removal notifications, you can call StopListening() to release resources and avoid the logging and other actions from the listeners.

Exceptions

ArgumentException

Thrown when transport is None.

UnauthorizedAccessException

Thrown when attempting to find YubiKeys for the transport HidFido on Windows, and the application is not running in an elevated state (e.g. "Run as administrator").

GetHashCode() 

public override int GetHashCode()

Returns

int

HasSameParentDevice(IDevice) 

protected bool HasSameParentDevice(IDevice device)

Parameters

device IDevice

Returns

bool

LockConfiguration(ReadOnlySpan<byte>)

Sets a configuration lock code, which prevents changes to YubiKey's user-settable IYubiKeyDeviceInfo values.

public void LockConfiguration(ReadOnlySpan<byte> lockCode)

Parameters

lockCode ReadOnlySpan<byte>

This lock code must have a length equal to LockCodeLength, and cannot be all zeros.

Remarks

Requires firmware version >= 5.0.0.

See ConfigurationLocked.

Once the lock code is set, no changes can be made to the YubiKey's user-settable IYubiKeyDeviceInfo values. This will block operations that attempt to modify those values, such as SetEnabledUsbCapabilities(YubiKeyCapabilities), SetAutoEjectTimeout(int), and even this one (LockConfiguration(ReadOnlySpan<byte>)). The lock code can be removed by calling UnlockConfiguration(ReadOnlySpan<byte>).

Exceptions

ArgumentException

The length of lockCode is invalid, or it contains all zeros.

InvalidOperationException

The command failed to complete.

NotSupportedException

An error occurred when attempting to connect to the device.

See Also

SetAutoEjectTimeout(int)

Sets the CCID auto-eject timeout (in seconds).

public void SetAutoEjectTimeout(int seconds)

Parameters

seconds int

The length of the timeout in seconds. The value must be in the range ushort.MinValue through ushort.MaxValue.

Remarks

YubiKeys prior to firmware version 5 must use SetLegacyDeviceConfiguration(YubiKeyCapabilities, byte, bool, int).

Modifies the value of AutoEjectTimeout. This requires the YubiKey's configuration to be unlocked (see ConfigurationLocked and UnlockConfiguration(ReadOnlySpan<byte>).

A value of 0 means that the timeout is disabled (the smart card will not be ejected automatically). See TouchEject for more information on setting up the smart card to automatically eject.

Exceptions

ArgumentOutOfRangeException

The value of seconds must be in the range ushort.MinValue through ushort.MaxValue.

InvalidOperationException

The command failed to complete.

NotSupportedException

An error occurred when attempting to connect to the device.

See Also

SetChallengeResponseTimeout(int)

Sets the timeout on OTP challenge-response operations.

public void SetChallengeResponseTimeout(int seconds)

Parameters

seconds int

The length of the timeout in seconds. The value must be in the range 0-255, where 0 resets the value to its default.

Remarks

YubiKeys prior to firmware version 5 must use SetLegacyDeviceConfiguration(YubiKeyCapabilities, byte, bool, int).

Modifies the value of ChallengeResponseTimeout. This requires the YubiKey's configuration to be unlocked (see ConfigurationLocked and UnlockConfiguration(ReadOnlySpan<byte>).

Exceptions

ArgumentOutOfRangeException

The value of seconds must be in the range 0-255.

InvalidOperationException

The command failed to complete.

NotSupportedException

An error occurred when attempting to connect to the device.

See Also

SetDeviceFlags(DeviceFlags)

Modifies the value of DeviceFlags.

public void SetDeviceFlags(DeviceFlags deviceFlags)

Parameters

deviceFlags DeviceFlags

The desired device settings. A set flag means that the setting is enabled. Otherwise, the capability is disabled.

Remarks

YubiKeys prior to firmware version 5 can use SetLegacyDeviceConfiguration(YubiKeyCapabilities, byte, bool, int) to enable TouchEject.

This operation requires the YubiKey's configuration to be unlocked (see ConfigurationLocked and UnlockConfiguration(ReadOnlySpan<byte>).

Exceptions

InvalidOperationException

The command failed to complete.

NotSupportedException

An error occurred when attempting to connect to the device.

See Also

SetEnabledNfcCapabilities(YubiKeyCapabilities)

Sets which NFC features are enabled (and disabled).

public void SetEnabledNfcCapabilities(YubiKeyCapabilities yubiKeyCapabilities)

Parameters

yubiKeyCapabilities YubiKeyCapabilities

The desired set of NFC features to enable on the YubiKey. A set flag means that the related capability is enabled. Otherwise, the capability is disabled.

Remarks

Requires firmware version >= 5.0.0.

Modifies the value of EnabledNfcCapabilities. This requires the YubiKey's configuration to be unlocked (see ConfigurationLocked and UnlockConfiguration(ReadOnlySpan<byte>).

The YubiKey will reboot as part of this change. This will cause this IYubiKeyDevice object to become stale, and future connection attempts using this object are likely to fail. To get fresh IYubiKeys, use the YubiKey enumeration functions such as FindAll() and FindByTransport(Transport).

To see which NFC features are available on the YubiKey, see AvailableNfcCapabilities.

This example shows how to enable only the Piv capability over NFC on all YubiKeys where Piv is available. All other capabilities will be disabled. The new set of enabled NFC capabilities will be printed to the console, showing that only Piv is enabled over NFC. 
IEnumerable<IYubiKeyDevice> yubiKeys =
    YubiKey.FindAll()
    .Where(d => d.AvailableNfcCapabilities.HasFlag(YubiKeyCapabilities.Piv));

foreach (IYubiKeyDevice yubiKey in yubiKeys)
{
device.SetEnabledNfcCapabilities(YubiKeyCapabilities.Piv);
}


// The devices may need a little time to finish rebooting
sleep(100);


// Get fresh IYubiKeys
IEnumerable<IYubiKeyDevice> freshYubiKeys =
YubiKey.FindAll()
.Where(d => d.AvailableNfcCapabilities.HasFlag(YubiKeyCapabilities.Piv));


int i = 1;
foreach (IYubiKeyDevice yubiKey in freshYubiKeys)
{
Console.PrintLine($"{i:} {yubiKey.SerialNumber} - {yubiKey.EnabledNfcCapabilities}");
}
 To change the state of some capabilities without affecting the others, you can do something like the following: 
IYubiKeyDevice yubiKey = YubiKey.FindAll().First();

YubiKeyCapabilities desiredNfcCapabilities = yubiKey.EnabledNfcCapabilities;


// Selectively enable Piv
desiredNfcCapabilities |= YubiKeyCapabilities.Piv;


// Selectively disable Otp
desiredNfcCapabilities &= ~YubiKeyCapabilities.Otp;


yubiKey.SetEnabledNfcCapabilities(desiredNfcCapabilities);

Exceptions

InvalidOperationException

The command failed to complete.

NotSupportedException

An error occurred when attempting to connect to the device.

See Also

SetEnabledUsbCapabilities(YubiKeyCapabilities)

Sets which USB features are enabled (and disabled).

public void SetEnabledUsbCapabilities(YubiKeyCapabilities yubiKeyCapabilities)

Parameters

yubiKeyCapabilities YubiKeyCapabilities

The desired set of USB features to enable on the YubiKey. A set flag means that the related capability is enabled. Otherwise, the capability is disabled. At least one available USB capability must be enabled.

Remarks

YubiKeys prior to firmware version 5 must use SetLegacyDeviceConfiguration(YubiKeyCapabilities, byte, bool, int).

Modifies the value of EnabledUsbCapabilities. This requires the YubiKey's configuration to be unlocked (see ConfigurationLocked and UnlockConfiguration(ReadOnlySpan<byte>).

The YubiKey will reboot as part of this change. This will cause this IYubiKeyDevice object to become stale, and future connection attempts using this object are likely to fail. To get fresh IYubiKeys, use the YubiKey enumeration functions such as FindAll() and FindByTransport(Transport).

To see which USB features are available on the YubiKey, see AvailableUsbCapabilities. At least one of these capabilities must be enabled.

This example shows how to enable only the Piv capability over USB on all YubiKeys where Piv is available. All other capabilities will be disabled. The new set of enabled USB capabilities will be printed to the console, showing that only Piv is enabled over USB. 
IEnumerable<IYubiKeyDevice> yubiKeys =
    YubiKey.FindAll()
    .Where(d => d.AvailableUsbCapabilities.HasFlag(YubiKeyCapabilities.Piv));

foreach (IYubiKeyDevice yubiKey in yubiKeys)
{
device.SetEnabledUsbCapabilities(YubiKeyCapabilities.Piv);
}


// The devices may need a little time to finish rebooting
sleep(100);


// Get fresh IYubiKeys
IEnumerable<IYubiKeyDevice> freshYubiKeys =
YubiKey.FindAll()
.Where(d => d.AvailableUsbCapabilities.HasFlag(YubiKeyCapabilities.Piv));


int i = 1;
foreach (IYubiKeyDevice yubiKey in freshYubiKeys)
{
Console.PrintLine($"{i:} {yubiKey.SerialNumber} - {yubiKey.EnabledUsbCapabilities}");
}
 To change the state of some capabilities without affecting the others, you can do something like the following: 
IYubiKeyDevice yubiKey = YubiKey.FindAll().First();

YubiKeyCapabilities desiredUsbCapabilities = yubiKey.EnabledUsbCapabilities;


// Selectively enable Piv
desiredUsbCapabilities |= YubiKeyCapabilities.Piv;


// Selectively disable Otp
desiredUsbCapabilities &= ~YubiKeyCapabilities.Otp;


yubiKey.SetEnabledUsbCapabilities(desiredUsbCapabilities);

Exceptions

InvalidOperationException

Either the command failed to complete.

NotSupportedException

An error occurred when attempting to connect to the device.

See Also

SetIsNfcRestricted(bool)

Sets the IsNfcRestricted on the YubiKeyDeviceInfo

public void SetIsNfcRestricted(bool enabled)

Parameters

enabled bool

Set this value to true to enable, otherwise false

Exceptions

InvalidOperationException

The command failed to complete.

SetLegacyDeviceConfiguration(YubiKeyCapabilities, byte, bool, int)

Manage configuration settings on YubiKeys prior to firmware version 5.

public void SetLegacyDeviceConfiguration(YubiKeyCapabilities yubiKeyInterfaces, byte challengeResponseTimeout, bool touchEjectEnabled, int autoEjectTimeout)

Parameters

yubiKeyInterfaces YubiKeyCapabilities

The desired set of USB interfaces to enable on the YubiKey. Any non-interface values are ignored. A set flag means that the related interface is enabled. Otherwise, the interface is disabled. At least one available USB interface must be enabled.

If touchEjectEnabled is true, then only the Ccid interface can be enabled.

challengeResponseTimeout byte

The length of the timeout in seconds. A value of 0 resets the timeout to its default duration.

touchEjectEnabled bool

true is the equivalent of setting TouchEject. And false disables it.

autoEjectTimeout int

The length of the timeout in seconds. If touchEjectEnabled is false, then the value must be 0. Otherwise, the value can be in the range ushort.MinValue through ushort.MaxValue. Where a value of 0 means that the timeout is disabled (the smart card will not be ejected automatically).

If this value is non-zero, then touchEjectEnabled must be set to true.

Remarks

This is the only configuration operation available to YubiKeys prior to firmware version 5. These YubiKeys have limited configuration settings, and all of them must be set at the same time. Important: once this operation succeeds, the YubiKey must be removed from the USB slot and then reinserted. This will allow the YubiKey to initialize all of the selected modes. This operation modifies the values related to

Interfaces are a subset of the YubiKeyCapabilities:

These interfaces enable or disable access to all applications that are dependent on it.

For YubiKeys with at least firmware version 5, it is recommended to use the other configuration operations in IYubiKeyDevice since they provide more fine control.

Exceptions

ArgumentException
ArgumentOutOfRangeException
InvalidOperationException

Either the command failed to complete, or the set of desired capabilities is invalid.

NotSupportedException

An error occurred when attempting to connect to the device.

See Also

SetTemporaryTouchThreshold(int)

Temporarily set the threshold at which a capacitive touch should be considered active.

public void SetTemporaryTouchThreshold(int value)

Parameters

value int

The touch threshold to apply to the YubiKey. Must be a value greater than 6.

Remarks

The field is using arbitrary units and has a default value of `6`. A higher value increases the sensor threshold which has the effect of decreasing the sensitivity of the sensor. Lower values increase the sensitivity, but callers cannot reduce the threshold below the default value of `6` which is locked in at manufacturing time. The value should not be any higher than `255`.

The value set here is only valid until the next time the YubiKey is power cycled. It does not persist.

You should typically not ever need to adjust this value. This is primarily used in the context of automatic provisioning and testing where the YubiKey is being "touched" by electrically grounding the sensor.

Exceptions

NotSupportedException

The YubiKey does not support this feature.

ArgumentOutOfRangeException

The value is less than 6 or greater than 255.

InvalidOperationException

The YubiKey encountered an error and could not set the setting.

ToString() 

public override string ToString()

Returns

string

TryConnect(byte[], out IYubiKeyConnection)

Attempt to connect to the YubiKey device.

public bool TryConnect(byte[] applicationId, out IYubiKeyConnection connection)

Parameters

applicationId byte[]

A byte array representing the smart card Application ID (AID) for the application to open.

connection IYubiKeyConnection

Out parameter containing the IYubiKeyConnection instance.

Returns

bool

Boolean indicating whether the call was successful.

TryConnect(byte[], ScpKeyParameters, out IScpYubiKeyConnection)

Attempt to connect to the YubiKey device over SCP using the specified ScpKeyParameters

public bool TryConnect(byte[] applicationId, ScpKeyParameters keyParameters, out IScpYubiKeyConnection connection)

Parameters

applicationId byte[]

The Iso7816 application ID to use for the connection.

keyParameters ScpKeyParameters

The ScpKeyParameters parameters for the SCP connection.

connection IScpYubiKeyConnection

The connection to the YubiKey, or null if unable to connect.

Returns

bool

True if the connection was successful, false otherwise.

Remarks

Note that SCP works only with SmartCard applications, namely PIV, OATH, OTP, Security Domain and YubiHsmAuth and OpenPgp. However, SCP03 is supported only on series 5 YubiKeys with firmware version on 5.3 and above. SCP 11 is supported only firmware version 5.7.2 and above.

Note also that the return is an instance of a class that implements IScpYubiKeyConnection which is a "subclass" of IYubiKeyConnection.

TryConnect(YubiKeyApplication, out IYubiKeyConnection)

Attempt to connect to the YubiKey device.

public bool TryConnect(YubiKeyApplication application, out IYubiKeyConnection connection)

Parameters

application YubiKeyApplication

The application to reference on the device.

connection IYubiKeyConnection

Out parameter containing the IYubiKeyConnection instance.

Returns

bool

Boolean indicating whether the call was successful.

TryConnect(YubiKeyApplication, ScpKeyParameters, out IScpYubiKeyConnection)

Attempt to connect to the YubiKey device over SCP using the specified ScpKeyParameters

public bool TryConnect(YubiKeyApplication application, ScpKeyParameters keyParameters, out IScpYubiKeyConnection connection)

Parameters

application YubiKeyApplication

The application to reference on the device.

keyParameters ScpKeyParameters

The ScpKeyParameters key set to use in making an SCP connection.

connection IScpYubiKeyConnection

Out parameter containing the IYubiKeyConnection instance.

Returns

bool

Boolean indicating whether the call was successful.

Remarks

Note that SCP works only with SmartCard applications, namely PIV, OATH, OTP, Security Domain and YubiHsmAuth and OpenPgp. However, SCP03 is supported only on series 5 YubiKeys with firmware version on 5.3 and above. SCP 11 is supported only firmware version 5.7.2 and above.

Note also that the return is an instance of a class that implements IScpYubiKeyConnection which is a "subclass" of IYubiKeyConnection.

TryGetYubiKey(int, out IYubiKeyDevice)

Get info on a specific YubiKey by serial number.

public static bool TryGetYubiKey(int serialNumber, out IYubiKeyDevice yubiKey)

Parameters

serialNumber int

Integer representation of the YubiKey serial number.

yubiKey IYubiKeyDevice

Out parameter that returns an IYubiKeyDevice instance.

Returns

bool

A bool indicating whether the YubiKey was found.

Remarks

This method will only be successful if the YubiKey was programmed with the flag SerialNumberUsbVisible.

UnlockConfiguration(ReadOnlySpan<byte>)

Removes the configuration lock code, allowing changes to YubiKey's user-settable IYubiKeyDeviceInfo values.

public void UnlockConfiguration(ReadOnlySpan<byte> lockCode)

Parameters

lockCode ReadOnlySpan<byte>

The lock code currently set on the YubiKey. This lock code must have a length equal to LockCodeLength.

Remarks

See ConfigurationLocked.

By removing the lock code, changes can be made to the YubiKey's user-settable IYubiKeyDeviceInfo values. To lock the configuration, use LockConfiguration(ReadOnlySpan<byte>).

If this operation is attempted on a device that is already unlocked, lockCode must be all zeros. Otherwise the operation will fail and throw an System.InvalidOperationException. In both cases, the device remains unlocked.

Exceptions

ArgumentException

The length of lockCode is invalid.

InvalidOperationException

The command failed to complete.

NotSupportedException

An error occurred when attempting to connect to the device.

See Also

Operators

operator ==(YubiKeyDevice, YubiKeyDevice) 

public static bool operator ==(YubiKeyDevice left, YubiKeyDevice right)

Parameters

left YubiKeyDevice
right YubiKeyDevice

Returns

bool

operator >(YubiKeyDevice, YubiKeyDevice) 

public static bool operator >(YubiKeyDevice left, YubiKeyDevice right)

Parameters

left YubiKeyDevice
right YubiKeyDevice

Returns

bool

operator >=(YubiKeyDevice, YubiKeyDevice) 

public static bool operator >=(YubiKeyDevice left, YubiKeyDevice right)

Parameters

left YubiKeyDevice
right YubiKeyDevice

Returns

bool

operator !=(YubiKeyDevice, YubiKeyDevice) 

public static bool operator !=(YubiKeyDevice left, YubiKeyDevice right)

Parameters

left YubiKeyDevice
right YubiKeyDevice

Returns

bool

operator <(YubiKeyDevice, YubiKeyDevice) 

public static bool operator <(YubiKeyDevice left, YubiKeyDevice right)

Parameters

left YubiKeyDevice
right YubiKeyDevice

Returns

bool

operator <=(YubiKeyDevice, YubiKeyDevice) 

public static bool operator <=(YubiKeyDevice left, YubiKeyDevice right)

Parameters

left YubiKeyDevice
right YubiKeyDevice

Returns

bool