Notation

Type names, attribute names and element names are written as code.

String literals are enclosed in “”, e.g. “UAF-TLV”.

In formulas we use “|” to denote byte wise concatenation operations.

DOM APIs are described using the ECMAScript [[!ECMA-262]] bindings for WebIDL [[!WebIDL]].

Symbolic constants such as U2FHID_MSG which are referred to when defining messages in this documents have their values defined in [[!U2FHIDHeader]] in the bibliography.

UAF specific terminology used in this document is defined in [[!FIDOGlossary]].

Definitions

U2FHID implementation rationale

The U2FHID protocol is designed with the following design objectives in mind

• Driver-less installation on all major host platforms
• Multi-application support with concurrent application access without the need for serialization and centralized dispatching.
• Fixed latency response and low protocol overhead
• Scalable method for U2FHID device discovery

Since HID data is sent as interrupt packets and multiple applications may access the HID stack at once, a non-trivial level of complexity has to be added to handle this.

Protocol structure and data framing

The U2F protocol is designed to be concurrent and state-less in such a way that each performed function is not dependent on previous actions. However, there has to be some form of "atomicity" that varies between the characteristics of the underlying transport protocol, which for the U2FHID protocol introduces the following terminology:

• Transaction
• Message
• Packet

A transaction is the highest level of aggregated functionality, which in turn consists of a request, followed by a response message. Once a request has been initiated, the transaction has to be entirely completed before a second transaction can take place and a response is never sent without a previous request.

Request- and response messages are in turn divided into individual fragments, known as packets. The packet is the smallest form of protocol data unit, which in the case of U2FHID are mapped into HID reports.

Concurrency and channels

Additional logic and overhead is required to allow a U2FHID device to deal with multiple "clients", i.e. multiple applications accessing the single resource through the HID stack. Each client communicates with a U2FHID device through a logical channel, where each application uses a unique 32-bit channel identifier for routing- and arbitration purposes.

A channel identifier is allocated by the U2F device to ensure its system-wide uniqueness. The actual algorithm for generation of channel identifiers is vendor specific and not defined by this specification.

Channel ID 0 is reserved and 0xffffffff is reserved for broadcast commands, i.e. at the time of channel allocation.

Message- and packet structure

Packets are one of two types, initialization packets and continuation packets. As the name suggests, the first packet sent in a message is an initialization packet, which also becomes the start of a transaction. If the entire message does not fit into one packet (including the U2FHID protocol overhead), one or more continuation packets have to be sent in strict ascending order to complete the message transfer.

A message sent from a host to a device is known as a request and a message sent from a device back to the host is known as a response. A request always triggers a response and response messages are never sent ad-hoc, i.e. without a prior request message.

The request and response messages have an identical structure. A transaction is started with the initialization packet of the request message and ends with the last packet of the response message.

Packets are always fixed size (defined by the endpoint- and HID report descriptors) and although all bytes may not be needed in a particular packet, the full size always has to be sent. Unused bytes should be set to zero.

An initialization packet is defined as

The command byte has always the highest bit set to distinguish it from a continuation packet, which is described below.

A continuation packet is defined as

With this approach, a message with a payload less or equal to (s - 7) may be sent as one packet. A larger message is then divided into one or more continuation packets, starting with sequence number 0, which then increments by one to a maximum of 127.

With a packet size of 64 bytes (max for full-speed devices), this means that the maximum message payload length is 64 - 7 + 128 * (64 - 5) = 7609 bytes.

Arbitration

In order to handle multiple channels and clients concurrency, the U2FHID protocol has to maintain certain internal states, block conflicting requests and maintain protocol integrity. The protocol relies on each client application (channel) behaves politely, i.e. does not actively act to destroy for other channels. With this said, a malign- or malfunctioning application can cause issues for other channels. Expected errors and potentially stalling applications should however be handled properly.

Channel locking

In order to deal with aggregated transactions that may not be interrupted, such as vendor specific tunneling of APDUs, a channel lock command may be implemented. By sending a channel lock command, the device prevents other channels from communicating with the device until the channel lock has timed out or been explicitly unlocked by the application.

This feature is optional and has not to be considered by general U2F HID applications.

Protocol version and compatibility

The U2FHID protocol is designed to be extensible, yet maintaining backwards compatibility to the extent it is applicable. This means that a U2FHID host shall support any version of a device with the command set available in that particular version.

Interface- and endpoint descriptors

The device implements two endpoints (except the control endpoint 0), one for IN- and one for OUT transfers. The packet size is vendor defined, but the reference implementation assumes a full-speed device with two 64-bytes endpoints.

Interface Descriptor

Endpoint 1 descriptor

Endpoint 2 descriptor

The actual endpoint order, intervals, endpoint numbers and endpoint packet size may be defined freely by the vendor and the host application is responsible for querying these values and handle these accordingly. For the sake of clarity, the values listed above are used in the following examples.

HID report descriptor and device discovery

A HID report descriptor is required for all HID devices, even though the reports and their interpretation (scope, range, etc.) makes very little sense from an operating system perspective. The U2FHID just provides two "raw" reports, which basically map directly to the IN and OUT endpoints. However, the HID report descriptor has an important purpose in U2FHID, as it is used for device discovery.

For the sake of clarity, a bit of high-level C-style abstraction is provided

// HID report descriptor

const uint8_t HID_ReportDescriptor[] = {
  HID_UsagePage ( FIDO_USAGE_PAGE ),
  HID_Usage ( FIDO_USAGE_U2FHID ),
  HID_Collection ( HID_Application ),
  HID_Usage ( FIDO_USAGE_DATA_IN ),
  HID_LogicalMin ( 0 ),
  HID_LogicalMaxS ( 0xff ),
  HID_ReportSize ( 8 ),
  HID_ReportCount ( HID_INPUT_REPORT_BYTES ),
  HID_Input ( HID_Data | HID_Absolute | HID_Variable ),
  HID_Usage ( FIDO_USAGE_DATA_OUT ),
  HID_LogicalMin ( 0 ),
  HID_LogicalMaxS ( 0xff ),
  HID_ReportSize ( 8 ),
  HID_ReportCount ( HID_OUTPUT_REPORT_BYTES ),
  HID_Output ( HID_Data | HID_Absolute | HID_Variable ),
HID_EndCollection
};
	  

A unique Usage Page is defined for the FIDO alliance and under this realm, a U2FHID Usage is defined as well. During U2FHID device discovery, all HID devices present in the system are examined and devices that match this usage pages and usage are then considered to be U2FHID devices.

The length values specified by the HID_INPUT_REPORT_BYTES and the HID_OUTPUT_REPORT_BYTES should typically match the respective endpoint sizes defined in the endpoint descriptors.

Mandatory commands

The following list describes the minimum set of commands required by an U2FHID device. Optional- and vendor-specific commands may be implemented as described in respective sections of this document.

Optional commands

The following commands are defined by this specification but are optional and does not have to be implemented.

Vendor specific commands

A U2FHID may implement additional vendor specific commands that are not defined in this specification, yet being U2FHID compliant. Such commands, if implemented must have a command in the range between U2FHID_VENDOR_FIRST and U2FHID_VENDOR_LAST.