Table of Contents

Interface IYubiKeyDevice

Namespace
Yubico.YubiKey
Assembly
Yubico.YubiKey.dll

Interface for class that provides device and enumeration capabilities.

public interface IYubiKeyDevice : IYubiKeyDeviceInfo
Inherited Members
Extension Methods

Properties

AvailableTransports

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

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.

Methods

Connect(byte[])

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

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.

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.

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.

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.

DeviceReset()

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

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.

LockConfiguration(ReadOnlySpan<byte>)

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

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).

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.

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.

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).

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).

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

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.

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

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.

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.

TryConnect(byte[], out IYubiKeyConnection)

Attempt to connect to the YubiKey device.

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

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.

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

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.

UnlockConfiguration(ReadOnlySpan<byte>)

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

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