6.1.1 Design rationale

CTAP messages are framed for USB transport using the HID (Human Interface Device) protocol. We henceforth refer to the protocol as CTAPHID. The CTAPHID 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 CTAPHID 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.

6.1.2 Protocol structure and data framing

The CTAP 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 CTAPHID 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 CTAPHID are mapped into HID reports.

6.1.3 Concurrency and channels

Additional logic and overhead is required to allow a CTAPHID device to deal with multiple "clients", i.e. multiple applications accessing the single resource through the HID stack. Each client communicates with a CTAPHID 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 FIDO authenticator 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.

6.1.4 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 CTAPHID 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.

6.1.5 Arbitration

In order to handle multiple channels and clients concurrency, the CTAPHID 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.

6.1.6 Channel locking

In order to deal with aggregated transactions that may not be interrupted, such as tunneling of vendor-specific commands, 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 CTAP HID applications.

6.1.7 Protocol version and compatibility

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

6.1.8 HID device implementation

This description assumes knowledge of the USB and HID specifications and is intended to provide the basics for implementing a CTAPHID device. There are several ways to implement USB devices and reviewing these different methods is beyond the scope of this document. This specification targets the interface part, where a device is regarded as either a single or multiple interface (composite) device.

The description further assumes (but is not limited to) a full-speed USB device (12 Mbit/s). Although not excluded per se, USB low-speed devices are not practical to use given the 8-byte report size limitation together with the protocol overhead.

// HID report descriptor

const uint8_t HID_ReportDescriptor[] = {
  HID_UsagePage ( FIDO_USAGE_PAGE ),
  HID_Usage ( FIDO_USAGE_CTAPHID ),
  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
};

6.1.9 CTAPHID commands

The CTAPHID protocol implements the following commands.

6.2.1 Conformance

6.2.2 Protocol

The general protocol between a FIDO 2.0 client and an authenticator over NFC is as follows:

1. Client sends an applet selection command
2. Authenticator replies with success
3. Client sends a command for an operation (MakeCredential or GetAssertion)
4. Authenticator replies with response data or error

6.2.3 Applet selection

A successful Select allows the client to know that the applet is present and active. A client SHALL send a Select to the authenticator before any other command.

The FIDO 2.0 AID consists of the following fields:

The command to select the FIDO 2.0 applet is:

In response to the applet selection command, the FIDO authenticator SHALL reply with its version string in the successful response. In this writing, the version string is "TBD", hence a successful response to the applet selection command would consist of the following bytes:

6.2.4 Framing

Conceptually, framing defines an encapsulation of FIDO 2.0 commands. In NFC, this encapsulation is done in an APDU following [ISOIEC-7816-4-2013]. Fragmentation, if needed, is discussed in the following paragraph.

6.2.5 APDU length

Length fields (Lc and Le) can be short (encoding a length up to 255) or extended (encoding a length up to 65535).

Some responses may not fit into a short APDU response. For this reason, FIDO 2.0 authenticators MUST respond in the following way:

• If the request was encoded using extended length APDU encoding, the authenticator MUST respond using the extended length APDU response format.
• If the request was encoded using short APDU encoding, the authenticator MUST respond using ISO 7816-4 APDU chaining.

6.3.1 Conformance

Authenticator and Client devices using BLE SHALL conform to Bluetooth Core Specification 4.0 or later [BTCORE]

Bluetooth(tm) SIG specified UUID values SHALL be found on the Assigned Numbers website [BTASSNUM]

6.3.2 Pairing

BLE is a long-range wireless protocol and thus has several implications for privacy, security, and overall user-experience. Because it is wireless, BLE may be subject to monitoring, injection, and other network-level attacks.

For these reasons, Clients and Authenticators MUST create and use a long-term link key (LTK) and SHALL encrypt all communications. Authenticator MUST never use short term keys.

Because BLE has poor ranging (i.e., there is no good indication of proximity), it may not be clear to a FIDO Client with which BLE Authenticator it should communicate. Pairing is the only mechanism defined in this protocol to ensure that FIDO Clients are interacting with the expected BLE Authenticator. As a result, Authenticator manufacturers SHOULD instruct users to avoid performing Bluetooth pairing in a public space such as a cafe, shop or train station.

One disadvantage of using standard Bluetooth pairing is that the pairing is "system-wide" on most operating systems. That is, if an Authenticator is paired to a FIDO Client which resides on an operating system where Bluetooth pairing is "system-wide", then any application on that device might be able to interact with an Authenticator. This issue is discussed further in Implementation Considerations.

6.3.3 Link Security

For BLE connections, the Authenticator SHALL enforce Security Mode 1, Level 2 (unauthenticated pairing with encryption) before any FIDO 2.0 messages are exchanged.

6.3.4 Framing

Conceptually, framing defines an encapsulation of FIDO 2.0 raw messages responsible for correct transmission of a single request and its response by the transport layer.

All requests and their responses are conceptually written as a single frame. The format of the requests and responses is given first as complete frames. Fragmentation is discussed next for each type of transport layer.

6.3.5 GATT Service Description

This profile defines two roles: FIDO Authenticator and FIDO Client.

• The FIDO Client shall be a GATT Client
• The FIDO Authenticator shall be a GATT Server

The following figure illustrates the mandatory services and characteristics that SHALL be offered by a FIDO Authenticator as part of its GATT server:

The table below summarizes additional GATT sub-procedure requirements for a FIDO Authenticator (GATT Server) beyond those required by all GATT Servers.

The table below summarizes additional GATT sub-procedure requirements for a FIDO 2.0 Client (GATT Client) beyond those required by all GATT Clients.

(*): Mandatory to support at least one of these sub-procedures.

(**): Mandatory to support at least one of these sub-procedures.

Other GATT sub-procedures may be used if supported by both client and server.

Specifics of each service are explained below. In the following descriptions: all values are big-endian coded, all strings are in UTF-8 encoding, and any characteristics not mentioned explicitly are optional.

6.3.6 Protocol Overview

The general overview of the communication protocol follows:

1. Authenticator advertises the FIDO 2.0 Service.
2. Client scans for Authenticator advertising the FIDO 2.0 Service.
3. Client performs characteristic discovery on the Authenticator.
4. If not already paired, the Client and Authenticator SHALL perform BLE pairing and create a LTK. Authenticator SHALL only allow connections from previously bonded Clients without user intervention.
5. Client reads the fido2ControlPointLength characteristic.
6. Client registers for notifications on the fido2Status characteristic.
7. Client writes a request (e.g., an enroll request) into the fido2ControlPoint characteristic.
8. Authenticator evaluates the request and responds by sending notifications over fido2Status characteristic.
9. The protocol completes when either:
   • The Client unregisters for notifications on the fido2Status characteristic, or:
   • The connection times out and is closed by the Authenticator.

6.3.7 Authenticator Advertising Format

When advertising, the Authenticator SHALL advertise the FIDO 2.0 service UUID.

When advertising, the Authenticator MAY include the TxPower value in the advertisement (see [BTXPLAD]).

The advertisement MAY also carry a device name which is distinctive and user-identifiable. For example, "ACME Key" would be an appropriate name, while "XJS4" would not be.

The Authenticator SHALL also implement the Generic Access Profile [BTGAP] and Device Information Service [BTDIS], both of which also provide a user-friendly name for the device that could be used by the Client.

It is not specified when or how often an Authenticator should advertise, instead that flexibility is left to manufacturers.

6.3.8 Requests

Clients SHOULD make requests by connecting to the Authenticator and performing a write into the fido2ControlPoint characteristic.

6.3.9 Responses

Authenticators SHOULD respond to Clients by sending notifications on the fido2Status characteristic.

Some Authenticators might alert users or prompt them to complete the test of user presence (e.g., via sound, light, vibration) Upon receiving any request, the Authenticators SHALL send KEEPALIVE commands every kKeepAliveMillis milliseconds until completing processing the commands. While the Authenticator is processing the request the KEEPALIVE command will contain status PROCESSING. If the Authenticator is waiting to complete the Test of User Presence, the KEEPALIVE command will contains status TUP_NEEDED. While waiting to complete the Test of User Presence, the Authenticator MAY alert the user (e.g., by flashing) in order to prompt the user to complete the test of user presence. As soon the Authenticator has completed processing and confirmed user presence, it SHALL stop sending KEEPALIVE commands, and send the reply.

Upon receiving a KEEPALIVE command, the Client SHALL assume the Authenticator is still processing the command; the Client SHALL not resend the command. The Authenticator SHALL continue sending KEEPALIVE messages at least every kKeepAliveMillis to indicate that it is still handling the request. Until a client-defined timeout occurs, the Client SHALL NOT move on to other devices when it receives a KEEPALIVE with TUP_NEEDED status, as it knows this is a device that can satisfy its request.

6.3.10 Framing fragmentation

A single request/response sent over BLE MAY be split over multiple writes and notifications, due to the inherent limitations of BLE which is not currently meant for large messages. Frames are fragmented in the following way:

A frame is divided into an initialization fragment and one or more continuation fragments.

An initialization fragment is defined as:

where maxLen is the maximum packet size supported by the characteristic or notification.

In other words, the start of an initialization fragment is indicated by setting the high bit in the first byte. The subsequent two bytes indicate the total length of the frame, in big-endian order. The first maxLen - 3 bytes of data follow.

Continuation fragments are defined as:

where maxLen is the maximum packet size supported by the characteristic or notification.

In other words, continuation fragments begin with a sequence number, beginning at 0, implicitly with the high bit cleared. The sequence number must wrap around to 0 after reaching the maximum sequence number of 0x7f.

Example for sending a PING command with 40 bytes of data with a maxLen of 20 bytes:

Example for sending a ping command with 400 bytes of data with a maxLen of 512 bytes:

6.3.11 Implementation Considerations