Class HidDevice
Base class for all HID devices represented by Yubico .NET-based SDKs.
public abstract class HidDevice : IHidDevice, IDevice- Inheritance
-
objectHidDevice
- Implements
Remarks
Yubico products, such as the YubiKey, can expose Human Interface Devices (HID) through their USB interfaces. The most common types of HIDs are keyboards and mice, but other types of devices exist as well. At this time, Keyboards and the custom "FIDO" type are the most interesting to this SDK. Implementations of this class should support finding all HID devices.
Constructors
HidDevice(string)
Constructs a HidDevice.
protected HidDevice(string path)Parameters
pathstring
Properties
LastAccessed
The time when this device was last accessed.
public DateTime LastAccessed { get; protected set; }Property Value
- DateTime
Remarks
Certain Yubico devices, such as the YubiKey, require a short delay before switching to and communicating with a different USB interface. This is called the reclaim timeout. The YubiKey SDK must keep track of the last interface to have been accessed and when in order to properly implement this delay.
ParentDeviceId
A unique identifier corresponding to the parent USB composite device, if available.
public string? ParentDeviceId { get; protected set; }Property Value
- string
Remarks
Certain devices that this SDK works with, like the YubiKey, are presented to the operating system as a composite device. This means that, to the operating system, multiple devices may be detected even though you have only plugged in one physical device. OSes that do this still expose a single "composite" device in their device tree. This is the common parent across all of the sub-devices.
Keeping track of this information, if available, can greatly increase the SDK's performance when it attempts to reconstruct the single, composite device out of all of the sub-devices. This isn't always possible, however, as the OS services that we use to enumerate the sub-devices don't always provide much information about its parent device. macOS and Windows 7, for example, cannot provide parent information for smart card devices. In those cases, we'll have to make do and attempt to match these devices some other way.
Path
Gets the platform defined path to the device.
public string Path { get; }Property Value
- string
Remarks
The exact meaning of this property may vary between operating systems and device types. The SDK treats this property as an opaque value and only uses it to check for uniqueness across device instances. It is strongly recommended that you do not take a dependency on the exact format or meaning of the value of this property.
ProductId
A hardware identifier indicating the product that this device represents.
public short ProductId { get; protected set; }Property Value
- short
Remarks
The Product ID is an identifier defined by the USB specification. The product ID is a 16-bit number that can be used to identify and differentiate different products produced by a given vendor. Values for the IDs are determined by the vendor. This means that different manufacturers may produce devices that have the same ID. Product IDs are only expected to be unique within the scope of a vendor.
Product IDs also don't guarantee that devices are the same physical model or product revision - only that the devices behave the same as far as USB communication is concerned. A single device may also expose different product IDs based on its configuration. An example of this behavior is with the YubiKey. The YubiKey is a composite USB device, meaning that it exposes multiple child devices (keyboard, FIDO, and smart card reader). It is possible to configure the YubiKey so that only a subset of those child devices are present. The product ID enumerated by USB will change, depending on which child devices are present.
Usage
A HID-specific hardware identifier indicating the type of device this is.
public short Usage { get; protected set; }Property Value
- short
Remarks
The HID specification defines a pair of values called the Usage. Usages are part of the HID report descriptor and are used to inform an application developer what the HID device is supposed to represent. If a device has more than one usage, the value here is considered to be the "primary" usage.
This property defines the "Usage ID" portion of the usage field. It is a 16-bit unsigned value. The usage ID
is used to select individual usage on a UsagePage. That is, it helps further specify the type
of device, or device interaction, that this object represents. Note: This field is of type short, but
is intended to be treated as unsigned. Casting to a ushort is permitted.
The value of this property is determined by the appropriate HID specification for the device in question. Knowing this value for something other than a generic HID type (such as keyboard, mouse, or joystick) may require locating additional specifications, as vendor defined values are allowed.
UsagePage
A HID-specific hardware identifier indicating the type of device this is.
public HidUsagePage UsagePage { get; protected set; }Property Value
VendorId
A hardware identifier indicating the vendor of this device.
public short VendorId { get; protected set; }Property Value
- short
Remarks
The Vendor ID is an identifier defined by the USB specification. Compliant USB devices, such as the YubiKey,
will have a unique vendor identifier assigned to them. In Yubico's case, this value is 0x1050. Other
manufacturers should have different numbers. No other manufacturer should create a device with a vendor ID
of 0x1050, however nothing prevents a malicious or otherwise non-compliant device from existing. So, while
you can make some assumptions about a device that matches your expected vendor ID, other steps should be
taken to verify that you are communicating with a genuine device. These steps will be device dependent and
are out of the scope of this document.
Methods
ConnectToFeatureReports()
Opens a connection to the human interface device's feature reports.
public abstract IHidConnection ConnectToFeatureReports()Returns
- IHidConnection
An active connection to the device. IHidConnection implements System.IDisposable, so please call System.IDisposable.Dispose() when you are finished with this object.
Remarks
The HID specification defines three report types that can be used to interact directly with the device: input, output, and feature. This method connects to the feature report mechanism.
Feature reports are often used to describe device configuration that can be sent to the device. In the context of the YubiKey SDK, feature reports are used to interact with the YubiKey's OTP application.
ConnectToIOReports()
Opens a connection to the human interface device's input/output reports.
public abstract IHidConnection ConnectToIOReports()Returns
- IHidConnection
An active connection to the device. IHidConnection implements System.IDisposable, so please call System.IDisposable.Dispose() when you are finished with this object.
Remarks
The HID specification defines three report types that can be used to interact directly with the device: input, output, and feature. This method connects to the input and output report mechanisms.
Input reports are often used to describe information on the current state of a HID device. Output reports are used to send data to the device, and can be used to control its state. In the context of the YubiKey SDK, input and output reports are used to interact with the YubiKey's FIDO application.
GetHidDevices()
Get a list of all the HIDs present on this computer.
public static IEnumerable<HidDevice> GetHidDevices()Returns
- IEnumerable<HidDevice>
An enumeration of all HIDs found on this computer. No connection to these devices has been established yet.
Exceptions
- PlatformNotSupportedException
Support for this operating system platform has not been added to the SDK yet.
ToString()
public override string ToString()Returns
- string