Like a USB keyboard, YubiKeys work via inputting scan codes as opposed to actual characters. This means that when you type, the keyboard only sends the key number, or “scan code”, which the computer then translates depending on your keyboard settings.
This presents an issue as there are many different keyboard layouts in use in the world today. In order to mitigate the problem, the YubiKey only uses modhex (modified hexadecimal for short) characters, which are characters which are mapped to by the same scan codes in almost all keyboard layouts. If your chosen keyboard layout is not one of those covered by the modhex system (like Dvorak, etc), your YubiKey might not be able to output the characters correctly. If this is true for you, here are 3 ways to resolve the issue.
Option 1
Our recommended “best practice” is to switch to a US standard keyboard layout when entering the OTP and switching back when done. When properly configured this is quick and convenient – in a Windows environment, for example, pressing Windows Key + Space will allow one to quickly switch to an alternative keyboard layout. On Macs running Monterey (macOS 12) or newer, the fn or Globe key can be configured to switch layouts (or Change Input Source) via System Preferences > Keyboard.
Option 2
If you are trying to output digits (0-9) with the French AZERTY keyboard layout, you can hold the Shift key on your keyboard while using the YubiKey, or enable the flag shown below in the YubiKey Personalization Tool. After checking the box next to Use numeric keypad for digits (2.3+), click Update Settings..., select one of the configuration slots, and click Update.
Option 3
If neither of the previous options are possible for you, another solution would be to modify the scanmap used by your YubiKey. This feature requires the command line version of the cross-platform YubiKey Personalization Tool and, after performing the operation, your YubiKey will only work properly on the keyboard layout that you have modified it for. For instance, if you modified it for a Dvorak keyboard layout, it can only be used on the Dvorak keyboard layout.
The YubiKey uses the following alphabet:
cbdefghijklnrtuvCBDEFGHIJKLNRTUV0123456789\t\r
The scanmap is the 1 byte scan code for each of those characters. So for a US standard keyboard layout (and the YubiKey default), the scanmap is:
06050708090a0b0c0d0e0f111517181986858788898a8b8c8d8e8f9195979899271e1f202122232425269e2b28
To set the scanmap, use the -S argument of the ykpersonalize tool and then affix the desired scanmap after. Shown below are some example scanmaps.
Simplified US Dvorak:
ykpersonalize -S0c110b071c180d0a0619130f120e09378c918b879c988d8a8699938f928e89b7271e1f202122232425269e2b28
French AZERTY:
ykpersonalize -S06050708090a0b0c0d0e0f111517181986858788898a8b8c8d8e8f9195979899a79e9fa0a1a2a3a4a5a6382b28
Turkish QWERTY (with a dotless i instead of a standard i):
ykpersonalize -S06050708090a0b340d0e0f111517181986858788898a8b8c8d8e8f9195979899271e1f202122232425269e2b28
Note that you must remove any whitespace present in these examples before using the values. Leaving the argument empty will reset the scanmap to the YubiKey’s default.
The screenshot above shows a YubiKey 5 Series scanmap being configured for the Dvorak keyboard layout.