The Yubico One Time Password scheme was developed by Yubico to take full advantage of the functionality of the YubiKey. It provides a path to automate the linkage between an account and authenticator at registration, security that the OTP generated may only be used once, and the assurance that the authenticator and server will never fall out of sync. The Yubico OTP further includes the advantages of traditional OTPs, in that since the code is text based, it can be used across almost every site, service and interface.
The Yubico OTP, like other OTPs, was designed to be used as a second factor authenticator in addition to username and password, as well as simple to implement for client services and systems. When implementing the Yubico OTP, developers have the option to either utilize the YubiCloud Yubico OTP Online Validation service, or stand up their own servers.
Yubico has declared end-of-life for the YubiKey Validation Server (YK-VAL) and YubiKey Key Storage Module (YK-KSM). These have been moved to YubicoLabs as a reference architecture. See article, YK-VAL, YK-KSM and YubiHSM 1 End-of-Life.
Yubico OTP Characteristics
To take full advantage of the YubiKey’s ability to output directly to a host computer, the Yubico OTP is 44 characters in length. This allows for information to be encrypted and passed to a validation server, unlike the more commonly used 6 to 8 digit OATH OTPs, which are only checked if they are identical to locally generated codes.
The first 12 characters of each OTP generated by the YubiKey remain constant over every OTP generated. These characters are called the Public ID, and are used to identify the YubiKey which generated the OTP. Integrators can use the Public ID to associate a YubiKey with an account, checking before the OTP is even validated if the correct YubiKey is being used. Further, since the Public ID is part of every OTP submitted, it can be captured during registration, automating the linkage between the YubiKey device and account.
The remaining 32 characters are a 128-bit AES-128 encrypted string containing information for validating the authenticity of the OTP. Each YubiKey uses a unique AES key, ensuring that should the key of one Yubico OTP become compromised, it does not affect any other users. The information encrypted includes a Private ID, Session and Usage Counters, a timer value, a checksum and 4 bytes of random data. For full details on these components, refer to https://developers.yubico.com/OTP/OTPs_Explained.html.
Since the usage counters are encrypted in the Yubico OTP string, the YubiKey and OTP validation server will never get out of sync - the validation server can update the values it has for the YubiKey on each successfully decrypted OTP. For more details, see the YubiCloud and the Yubico Validation Server.
Modhex
The Yubico OTP was designed to be compatible across as wide a range of keyboard languages as possible. The character set used is a Modified Hexadecimal encoding, commonly referred to as Modhex.
The character representation may look a bit strange at first sight but is designed to cope with various keyboard layouts causing potential ambiguities when decoded. USB keyboards send their keystrokes by the means of “scan codes” rather than the actual character representation.The translation to keystrokes is done by the computer. For the YubiKey, it is critical that the same code is generated if it is inserted in a German computer having a QWERTZ, a French with an AZERTY or a US one with a QWERTY layout. The “Modhex”, or Modified Hexadecimal coding was invented by Yubico to just use the specific characters that don’t create any ambiguities. The Modhex coding packs four bits of information in each keystroke. This gives that a 128-bit OTP string requires 128 / 4 = 32 Characters.
The Modhex mapping is based on hexadecimal coding but the output is mapped into the following characters, found at the same scan code address on most keyboards
Hex | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | a | b | c | d | e | f | |
ModHex | c | b | d | e | f | g | h | i | j | k | l | n | r | t | u | v |
For more details, see the Modhex Converter.
Yubico OTP Validation
The Yubico OTP takes advantage of the full range of information encrypted within during authentication. Broadly, the following steps are included in each Validation:
The YubiKey is inserted into the USB port. The computer detects it as an external USB HID keyboard.
The user touches the YubiKey OTP generation button.
Internally, a byte string is formed by concatenation of various internally stored and calculated fields, including as a non-volatile counter, a timer and a random number.
The byte string is encrypted with a 128-bit AES key.
The encrypted string is converted to a series of characters and sent as keystrokes via the keyboard port.
The generated string of keystrokes is then typically sent via an input dialog or a web form to a server or host application for verification. The basic steps for verification can be conceptually described as:
The received string is converted back to a byte string.
The byte string is decrypted using the same (symmetric) 128-bit AES key.
The string’s checksum is verified. If not valid, the OTP is rejected.
Additional fields are verified. If not valid, the OTP is rejected.
The non-volatile counter is compared with the previously received value. If lower than or equal to the stored value, the received OTP is rejected as a replay. If greater than the stored value, the received value is stored and the OTP is accepted as valid.
For a more in depth description of this process, refer to the Yubico Validation Server Algorithm.
The Yubico Validation Service is comprised of 2 servers; a Validation server which compares the counters and acts as the public facing interface and a Key Storage Module where the secrets for the Yubico OTPs are stored and OTPs are decrypted. Yubico offers both a Validation server and Key Storage Module to make standing up a personal validation server straightforward. Users can set up more than one of each type of server, and use the tooling built into them to keep each in sync. These servers and frameworks are described in more depth at Setup of a self-hosted Yubico OTP validation server.
Relevant pages:
Servers:
YubiCloud
For services and websites connected to the internet, Yubico offers a free Yubico OTP Validation service called the YubiCloud. Every YubiKey is programmed at the factory with a YubiCloud credential, removing the need to manage and upload secrets. The YubiCloud behaves in the same manner as a Yubico OTP Validation servers available as open source.
To make it simple to integrate the YubiCloud, Yubico offers client libraries as open source in a number of languages. These offerings can be accessed under the Yubico OTP Integrations Plug-ins page. Alternatively, it is a straightforward matter to create your own client - advice and direction on how to do so can be referenced at Getting Started Writing Clients.
Whether using a pre-built client or writing a new one, each client service will need an API key from Yubico. Directions on acquiring one are listed in Obtaining an API Key for YubiKey Development. Note that only the client service sending an OTP to the YubiCloud needs an API key; individual users utilizing the service do not.
