The FIDO U2F framework was designed to be able to support multiple Authenticator form factors. This document describes the communication protocol with Authenticators over Bluetooth classic (BT) and Bluetooth Low Energy (BLE).
There are multiple form factors possible for Authenticators. Some might be low cost, low power devices, and others might be implemented as an additional feature of a more powerful device, such as a smartphone. The design proposed here is meant to support multiple form factors, including but not necessarily limited to these two examples.
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]].
UAF specific terminology used in this document is defined in [[!FIDOGlossary]].
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [[!RFC2119]].
BT and BLE are long-range wireless protocols and thus have several implications for privacy, security, and overall user-experience. Because they are wireless, BT and 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 BT and BLE have poor ranging (i.e., there is no good indication of proximity), it may not be clear to a FIDO Client with which BT/BLE Authenticator it should communicate. Pairing is the only mechanism defined in this protocol to ensure that FIDO Clients are interacting with the expected BT/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.
For BLE connections, the Authenticator SHALL enforce Security
Mode 1, Level 2
(unauthenticated pairing with encryption)
before any U2F messages are exchanged.
For BT connections, the Authenticator SHOULD use Secure Simple Pairing
when possible, Security Mode 4
or better. Encryption
SHALL be enabled using a key size of 16 bytes before any U2F messages
are sent.
Conceptually, framing defines an encapsulation of U2F raw messages responsible for correct transmission of a single request and its response by the transport layer (Bluetooth Classic or Bluetooth Low Energy).
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.
Request frames must have the following format
Offset | Length | Mnemonic | Description |
---|---|---|---|
0 | 1 | CMD | Command identifier |
1 | 1 | HLEN | High part of data length |
2 | 1 | LLEN | Low part of data length |
3 | s | DATA | Data (s is equal to the length) |
Supported commands are PING
and MSG
.
The constant values for them are described below.
Data format is defined in [U2FRAWMESSAGES].
Response frames must have the following format, which share a similar format to the request frames:
Offset | Length | Mnemonic | Description |
---|---|---|---|
0 | 1 | STAT | Response status |
1 | 1 | HLEN | High part of data length |
2 | 1 | LLEN | Low part of data length |
3 | s | DATA | Data (s is equal to the length) |
When the status byte in the response is the same as the command
byte in the request, the response is a successful response. The
value ERROR
indicates an error, and the response data
contains an error code as a variable-length, big-endian integer. The
constant value for ERROR
is described below. The set of
error values is TBD.
Note that the errors sent in this response are errors at the
encapsulation layer, e.g., indicating an incorrectly
formatted request, or possibly an error communicating with the
Authenticator’s U2F message processing layer. Errors reported by the
U2F message processing layer itself are considered a success from
the encapsulation layer’s point of view, and are reported as a
complete MSG
response.
Data format is defined in [U2FRAWMESSAGES]. Note that as per [U2FRAWMESSAGES] (and unlike the NFC transport specification), all communication SHALL be done using extended length APDU format.
Constant | Value |
---|---|
PING | 0x81 |
MSG | 0x83 |
ERROR | 0xbf |
The general procedure is as follows:
When the Authenticator is in Bluetooth discovery mode, it SHOULD include a device name in the Extended Inquiry Response (EIR) packet. The device name should be distinctive and user-identifiable. For example, "ACME Key" would be an appropriate name, while "XJS4" would not be.
The Authenticator SHALL contain a Service Discovery Protocol (SDP) record with the following data:
If one or both of the Authenticator and Client only supports Classic Bluetooth, they SHALL communicate over RFCOMM.
If both Authenticator and Client are dual mode devices, they SHALL communicate using GATT over L2CAP on the BREDR connection.
No fragmentation is supported as communication over RFCOMM should be able to handle all messages without fragmentation.
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]
This profile defines two roles: FIDO Authenticator and FIDO Client.
The following graphic 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.
GATT Sub-Procedure | Requirements |
---|---|
Write Characteristic Value | Mandatory
|
Notifications | Mandatory
|
Read Characteristic Descriptors | Mandatory
|
Write Characteristic Descriptors | Mandatory
|
The table below summarizes additional GATT sub-procedure requirements for a FIDO Client (GATT Client) beyond those required by all GATT Clients.
GATT Sub-Procedure | Requirements |
---|---|
Discover All Primary Services | (*)
|
Discover Primary Services by Service UUID | (*)
|
Discover All Characteristics of a Service | (**)
|
Discover Characteristics by UUID | (**)
|
Discover All Characteristic Descriptors | Mandatory
|
Read Characteristic Value | Mandatory
|
Write Characteristic Value | Mandatory
|
Notification | Mandatory
|
Read Characteristic Descriptors | Mandatory
|
Write Characteristic Descriptors | Mandatory
|
(*): 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.
An Authenticator SHALL implement the U2F Service described below. The UUID for the FIDO U2F GATT service is TBD (it is being standardized by the Bluetooth SIG). The service contains the following characteristics:
Characteristic Name | Mnemonic | Property | Length | UUID |
---|---|---|---|---|
U2F Control Point | u2fControlPoint | Write | Defined by Vendor (20-512 bytes) | TBD |
U2F Status | u2fStatus | Notify | Defined by Vendor (20-512 bytes) | TBD |
U2F Control Point Length | u2fControlPointLength | Read | 2 bytes | TBD |
U2F Service Revision | u2fServiceRevision | Read | Defined by Vendor (20-512 bytes) | 0x2A28 |
u2fControlPoint
is a write-only command buffer.
u2fStatus
is a notify-only response attribute.
u2fControlPointLength
defines the size in bytes of
u2fControlPoint
. This value SHALL be between 20 and
512.
u2fServiceRevision
defines the
revision of the U2F Service. The value is a UTF-8 string. For
this version of the specification, the value
u2fServiceRevision
SHALL be 1.0
or in
raw bytes: 0x312e30
.
The u2fServiceRevision
Characteristic MAY include
a Characteristic Presentation Format descriptor with format value
0x19, UTF-8 String
.
An Authenticator SHALL implement the Device Information Service [BTDIS] with the following characteristics:
All values for the Device Information Service are left to the vendors. However, vendors should not create uniquely identifiable values so that Authenticators do not become a method of tracking users.
Every Authenticator SHALL implement the Generic Access Service [BTGAS] with the following characteristics:
The general overview of the communication protocol follows:
u2fControlPointLength
characteristic.
u2fStatus
characteristic.
u2fControlPoint
characteristic.
u2fStatus
characteristic.
When advertising, the Authenticator SHALL advertise the FIDO U2F 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 which 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.
Clients SHOULD make requests by connecting to the Authenticator
and performing a write into the u2fControlPoint
characteristic.
Authenticators SHOULD respond to Clients by sending notifications
on the u2fStatus
characteristic.
Some Authenticators might alert users or prompt them to complete the test of user presence (e.g., via sound, light, vibration, etc.) Upon receiving a valid request (containing a known key handle), the Authenticators MAY alert the user and MAY use a short delay before sending a response. In this case, before the user has completed the test of user presence, the Authenticator SHALL respond with SW_CONDITIONS_NOT_SATISFIED [U2FRAWMESSAGES]. Upon receiving an SW_CONDITIONS_NOT_SATISFIED message, the Client SHALL assume the Authenticator is still processing the command; the Client SHALL not resend the command. Until a timeout occurs, the Client SHALL NOT move on to other devices when it receives a SW_CONDITIONS_NOT_SATISFIED, as it knows this is a device that can satisfy its request.
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:
Offset | Length | Mnemonic | Description |
---|---|---|---|
0 | 1 | CMD | Command identifier |
1 | 1 | HLEN | High part of data length |
2 | 1 | LLEN | Low part of data length |
3 | maxLen - 3 | DATA | Data |
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:
Offset | Length | Mnemonic | Description |
---|---|---|---|
0 | 1 | SEQ | Packet sequence 0x00..0x7f (high bit always cleared) |
1 | maxLen - 1 | DATA | Data |
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.
Example for sending a PING
command with 40 bytes of
data with a maxLen
of 20 bytes:
Frame | Bytes |
---|---|
0 | [810028] [17 bytes of data]
|
1 | [00] [19 bytes of data]
|
2 | [01] [4 bytes of data]
|
Example for sending a ping command with 400 bytes of data with a
maxLen
of 512 bytes:
Frame | Bytes |
---|---|
0 | [810190] [400 bytes of data]
|
As noted in the Pairing section, a 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 poses both security and privacy risks to users.
While Client operating system security is partly out of FIDO's scope, further revisions of this specification MAY propose mitigations for this issue.
The method to put the Authenticator into Pairing Mode should be such that it is not easy for the user to do accidentally especially if the pairing method is Just Works. For example, the action could be pressing a physically recessed button or pressing multiple buttons. A visible or audible cue that the Authenticator is in Pairing Mode should be considered. As a counter example, a silent, long press of a single non-recessed button is not advised as some users naturally hold buttons down during regular operation.
Upon completion of a command with a successful outcome, the
Authenticator can assume the Client is satisfied, and MAY reset
its state or power down. Upon completion with an error, the
Authenticator MUST assume that the Client MAY wish to cope with
the error, e.g., by sending a different command or
retrying the same one. If the Authenticator waits
kErrorWaitMillis
milliseconds after sending an error
response, and the Client does not send an additional command, the
Authenticator MAY assume the Client will not send an additional
command, and reset its state and/or power down.
Constant | Value |
---|---|
kErrorWaitMillis | 2000 milliseconds |
BLE does not have particularly high throughput, this can cause noticeable latency to the user if request/responses are large. Some ways that implementers can reduce latency are:
Though the standard doesn’t appear to mandate it (in any way that we’ve found thus far), advertising and device discovery seems to work better when the Authenticators advertise on all 3 advertising channels and not just one.
[BTASSNUM] Bluetooth Assigned Numbers. https://www.bluetooth.org/en-us/specification/assigned-numbers
[BTCORE] Bluetooth Core Specification 4.1. see https://www.bluetooth.org/en-us/specification/adopted-specifications
[BTDIS] Device Information Service V1.1. see https://www.bluetooth.org/en-us/specification/adopted-specifications
[BTGAP] Generic Access Profile. Bluetooth Core Specification 4.1, Volume 3, Part C, Section 12. see https://www.bluetooth.org/en-us/specification/adopted-specifications
[BTGAS] Generic Access Service. Bluetooth Core Specification 4.1, Volume 3, Part C, Section 12. see https://developer.bluetooth.org/gatt/services/Pages/ServiceViewer.aspx?u=org.bluetooth.service.generic_access.xml
[BTXPLAD] Bluetooth TX Power AD Type. Bluetooth Core Specification 4.1, Volume 3, Part C, Section 11. see https://www.bluetooth.org/en-us/specification/adopted-specifications
[U2FRAWMESSAGES] Dirk Balfanz, Jakob Ehrensvard. FIDO U2F Raw Message Formats, Aug 2014.