YubiKey-host device communication
YubiKeys can, depending on their components, communicate with host devices over USB, NFC, and/or Lightning interfaces.
USB communication
In order for the OTP application on the YubiKey to submit passwords (Yubico OTPs, OATH HOTPs, and static passwords) through a host device over USB, it must utilize the USB HID (Human Interface Device) communication protocol. The HID standard allows compliant hosts and USB peripherals, like keyboards and mice, to communicate without the need for specialized drivers.
The YubiKey essentially emulates a HID keyboard; each key on a keyboard is represented by a HID usage ID (in decimal and hexadecimal), which is collected into a HID usage report (sometimes referred to as a message). The YubiKey generates these usage reports to simulate keystrokes, and the usage reports are decoded by the host into the characters of a password.
HID reports
A HID report consists of eight bytes: the first byte represents a set of modifier key flags, the second byte is unused, and the final six bytes represent keys that are currently being pressed, sorted in the order they were pressed.
With HID, modifier key flags (e.g. the left-shift button) are used to, you guessed it, modify the keys included in the final six bytes of the HID report. If modifier key flags are not included in the report, the keys will be sent in their default format (letter keys are lowercase by default).
The following tables represent the bytes of a HID report and the bits in the modifier key flags byte:
| HID Report Bytes | Modifier Key Flags | |||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
* On Windows systems, this is the Windows key.
To send an uppercase "A" to a host device, the YubiKey must send the following usage report:
| Byte | Value | Description |
|---|---|---|
| 0 | 0x02 | The left shift (modifier key flag bit 1) is pressed. |
| 1 | 0x00 | (reserved) |
| 2 | 0xe1 | Usage ID for the left shift key. |
| 3 | 0x04 | Usage ID for the "A" key. |
| 4 - 7 | 0x00 | Unused bytes (no more keys pressed). |
HID keyboard layout challenges
A major challenge is that HID usage IDs correspond to physical locations on a keyboard, not the characters themselves. For example, on an English language keyboard, the top row of keys spells QWERTY, and on a German language keyboard, those same keys spell QWERTZ. However, the "Y" key on the English keyboard and the "Z" key on the German keyboard are represented by the same HID usage ID of 28 (0x1c).
Therefore, when programming a YubiKey slot with a static password, the SDK must be told which keyboard layout the host device is configured with in order to send the correct HID usage IDs for your static password characters.
Note
You can configure your keyboard layout in Windows regardless of the actual keyboard you have.
When specifying a keyboard layout, you must be absolutely sure that every host device your key is plugged into be set to the same keyboard layout. Going back to our example, if you program your YubiKey using an English layout, and someone plugs the key into a computer configured with a German layout, then all of the “Y” characters in your static password will be interpreted as “Z”.
But what should you do if you can't guarantee that the host device's keyboard layout will always be the same? And where does this leave Yubico OTPs and OATH HOTPs, which are generated by algorithms instead of manually configured by a user? To address these challenges, Yubico invented ModHex (modified hexadecimal), which is both a keyboard layout configuration and an encoding scheme.
For more details, see the article on ModHex.
Lightning communication
The Apple Lightning connector on the YubiKey 5Ci uses the iAP communication protocol (iPod Accessory Protocol). However, iAP also has support for HID through a tunneling mechanism, which allows the OTP application on the YubiKey to send and receive HID messages when connected over Lightning.
NFC communication
NFC-enabled YubiKeys communicate with host devices through close (wireless) contact with a host's NFC-reader via the NDEF (NFC Data Exchange Format) protocol.
Unlike HID communication, where passwords are sent as bytes that represent HID usage reports, NDEF sends text. When a YubiKey is scanned by an NFC reader, the key emits a URL containing the web address of an OTP validation server followed by the OTP.
Note
NFC is only compatible with Yubico OTPs and OATH HOTPs--static passwords can only be communicated through HID usage reports.