Introduction
This article will summarize various aspects of creating a U2F Host Library regarding the U2F specifications.
The Host library is the part that communicates between the so-called FIDO Client (web browser) and Authenticator (YubiKey, etc.). However, if a web browser is not available, U2F communication is not necessary.
However, if one wants to use FIDO authentication in a native application where a web browser is unavailable, they will need to create a Host library, as shown here. (This will no longer be necessary if the platform API supports it, such as Windows Hello.)
Table of Contents
Sequence
What the host library does
Communication with U2F devices
JavaScript API
Raw Message Format
APDU Format
HID Protocol
About FIDO2
Sequence
First, begin by checking the entire sequence of U2F.
At the time of registration
At the time of authentication
This is the U2F Challenge & Response diagram often seen, and this communication part between the Client and YubiKey is called CTAP.
Compared to the CTAP2 specification in FIDO2, it is also called CTAP1.
The client is usually a browser, but only Chrome implements it as U2F. (Firefox60 and later are also supported as WebAuthN)
What the host library does
The host library works behind the scenes with APIs such as the U2F JavaScript API. For example, at the time of registration.
Enumerate USB devices
Search for U2F devices
Write the registration request to the device
Read the response from the device
Next, an explanation of the operation after “3) Registration Request” during the implementation of FIDO U2F will be discussed.
Communication with U2F Device
The U2F specifications include U2F JavascriptAPI U2F, U2F Raw Message Formats, and U2F HID Protocol which are the low-level protocols of the device from the Client-side in order from Javascript API.
In regards to the specifications, there are three main points.
Point 1. U2F devices operate as HID devices
As stated in the specifications, the communication between the U2F device and the Client uses the HID (Human Interface Device) protocol, a common standard used in devices such as keyboards and mouses and can be used without a driver.
Point 2. The format for sending and receiving data is APDU Format
Although the HID protocol is used for communication, actual messages are sent in a format called APDU Format, a method of exchanging data for reading smart cards, etc. This APDU Format, which is the format in which the data is sent, consists of a header indicating the command, data length, and the data attached to it.
Point 3. Data is in the U2F Raw Message Formats
Also, the data to be sent in APDU is sent in a format known as U2F Raw Message Format.
Since the U2F Raw Message Format is a byte array data, if it is converted to a data format that JavaScript can handle, it can be handled in a data format such as JSON, like the API in Chrome.
In summary, it looks like this.
Upon understanding these three points, it will be significantly easier to follow along with reading the specs and Yubico’s reference code.
The following section will trace the registration phase and checking of the data.
For example, the following Registration Request from https://example.com via the JavaScript API was received.
First, to convert this data to Raw Message Formats, create a JSON String called ClientData.
The members of ClientData are "type," "challenge," "origin," and "cid," but when registering a U2F device, use
type: "navigator.id.finishEnrollment" fixed
challenge: Challenge string from the server.
origin: If it is HTTP communication, the domain must be authenticated.
cid: option. a JwkKey-style public key is used to sign a Token Binding called channel ID. This time, it is omitted.
On the Raw Message Formats side, a SHA256 hashed value of JSON is used, which is the Challenge Parameter. (Hexadecimal notation).
Web Safe Base64 Encoded JSON is sent to the server as ClientData.
The changing of "/" to "_" and "+" to "-" are known as Web Safe Base64 or URL Safe Base64. However, the padding is removed (i.e., the trailing === is cleared).
This parameter is only Base64 encoded for sending to the server and does not use this data for communication with the Authenticator.
Another parameter is the Application Parameter, which is the sha256 hash of appId("https://example.com").
The Registration Request Message is a combination of the two.
※FIDO U2F Raw Message 4.1 Fig. 2 Registration Request Message
APDU Format
Next, the U2F Raw Message format is sent to the HID device in APDU Format.
In APDU Format, the data length and command parameters must be specified in the header section, and the command parameters at registration are as follows.
There are two types of APDU data, Short Encoding, and Extended Length Encoding, and U2F uses Short Encoding.
※Le defines the maximum size of the response data but is ignored if the maximum length is set to 256 bytes.
HID Protocol
All that remains is sending the data to the HID device, but only 64 bytes can be written to the HID device simultaneously.
As with the APDU format, a header is attached, as shown below, so the actual data to be sent looks like this.
・※The channel ID is obtained when the device is initialized.
・※The seventh bit of the command is always 1
DATA is the APDU data mentioned earlier. While the total data size is 71 bytes (0x47), the HID packet is 64 bytes, so only 57 bytes can be sent, as 7 bytes are required for the header for HID Transport. The rest of the data is sent as sequence data in the following form.
Now read the response from the device.
In other words, this time, the process is reversed from HID protocol → APDU format → U2F Raw Message Format to get the response from the device.
About FIDO2
The U2F host-side communication is the same protocol used in CTAP2 for FIDO2.
CTAP2 has more PIN-related commands, more data to send, and a standardized format called CBOR.