OATH-HOTP
OATH HOTPs (Initiative for Open Authentication HMAC-based one-time passwords) are 6 or 8 digit unique passcodes that are used as the second factor during two-factor authentication.
When an OTP application slot on a YubiKey is configured for OATH HOTP, activating the slot (by touching the YubiKey while plugged into a host device over USB or scanning an NFC-enabled key with an NFC reader) will cause the generation of an HOTP. An HOTP looks like the following:
154916
In order to verify the authenticity of HOTPs, a validation server is needed. When an application receives an HOTP during a login attempt, it must send the HOTP to the server, which assesses whether the HOTP is valid and then reports the result to the application.
The SDK provides the functionality to configure an OTP application slot with an HOTP and control how HOTPs are communicated from a YubiKey to a host device.
You may have noticed that the YubiKey also has an OATH application, and the SDK provides the ability to configure the OATH application with both HOTPs and TOTPs (time-based OTPs). So why include OATH functionality in the OTP application if an OATH application exists? Early versions of the YubiKey (YubiKey 1 and 2) only had the OTP application. Providing SDK functionality for OATH within the OTP application is therefore a form of legacy support. For the average SDK user, we recommend using the OATH application instead of the OTP application for any OATH functionality needs.
OATH HOTP components and algorithm
OATH HOTPs are much simpler than Yubico OTPs. To generate an HOTP, the YubiKey uses the following elements:
- A counter (4 bytes)
- A unique secret key (20 bytes)
Note
At 4 bytes, the counter can be incremented up to 4,294,967,295 times (if the counter starts at 0). This means that even if you were to authenticate 1,000 times every day, it would take 11,767 years before the slot would need to be reconfigured with a new OATH HOTP credential. This is in contrast to the usage counter of Yubico OTPs, which, at 2 bytes in size, can only be incremented 65,535 times before reconfiguration is needed.
The HOTP is the product of encrypting the counter with the secret key via the HOTP algorithm as described in RFC-4226.
Both the YubiKey and the validation server store copies of the counter and secret key.
OATH HOTP generation and authentication with the YubiKey
When a slot that is configured for OATH HOTP is activated, the YubiKey’s counter is incremented by 1, and the HOTP is generated by encrypting the counter value with the secret key, both of which are stored in write-only memory on the YubiKey.
To authenticate a user, the HOTP has to be sent to and verified by a validation server. This server stores copies of the configuration’s counter and unique secret key. When an HOTP is sent for verification, the server’s counter value is incremented by 1, and the validation server uses its copies of the secret key and counter to compute the HOTP using the same algorithm. If the YubiKey-generated HOTP matches the server-generated HOTP, the user is authenticated.
If the HOTPs do not match, the validation server will compute additional HOTPs by incrementing the counter and encrypting it with the secret key. This counter incrementation is referred to as the “look-ahead” window. The look-ahead window is used to help keep the counters of the YubiKey and the validation server in sync. If the YubiKey generates an HOTP but does not send it to the validation server for verification, any subsequent HOTPs generated by the YubiKey will be flagged as invalid by the validation server because the counters are out of sync, and, therefore, the HOTP generated by the server will not match the YubiKey’s HOTP.
The size of the look-ahead window is set by the validation server. If the counter used in the YubiKey-generated HOTP falls outside of the look-ahead window, authentication will fail, and the OATH configuration on the YubiKey will need to be reset, with the new secret key and counter shared with the validation server.
OATH validation servers
At this time, Yubico does not provide a reference architecture for a self-hosted OATH HOTP validation server. It is up to the developer to either set up a self-hosted OATH validation server or utilize a commercial product.
OATH HOTP security
Unlike OATH TOTPs, which are only valid for a finite amount of time after being generated, HOTPs can be used indefinitely as long as their counter is equal to or higher than the counter stored on the validation server (and the counter is within the look-ahead window). Therefore, any HOTPs generated outside of the login process pose a security risk–a hacker could steal these credentials and use them to break into the accompanying account (until a new HOTP is generated and sent for verification). To protect against this scenario, we recommend that you provide a facility to “burn” HOTPs. Burning refers to the process of generating and submitting an HOTP for verification with the goal of simply updating the validation server's counter.
Also, if your application and validation server allow it, we recommend using the 8-digit HOTP over the 6-digit HOTP. The two additional digits provide a 100-fold increase in security.
Note
Given 10 options per digit (the numbers 0 through 9), there are 10^6 = 1,000,000 possible combinations for a 6-digit HOTP and 10^8 = 100,000,000 possible combinations for an 8-digit HOTP.
SDK functionality
The SDK's OATH HOTP functionality within the OTP application is rooted in the ConfigureHotp() method. This method allows you to configure one of the OTP application slots with an OATH HOTP. After configuration, that slot will generate an HOTP every time it is activated.
With ConfigureHotp(), you have the ability to provide your own secret key and initial counter value via UseKey() and UseInitialMovingFactor() or randomly generate the key with GenerateKey().
Note
Generated credentials will need to be shared with the validation server before they are cleared from memory. There is no way to extract credentials from the YubiKey after configuration.
By default, an OTP application slot configured for HOTP will generate 6-digit HOTPs. If you would like to generate 8-digit HOTPs, you must call the Use8Digits() method.
The YubiKey also allows you to control how the HOTP is sent to a host, depending on the intended use case. You can set a time delay between characters of the HOTP as they are sent to a host device with Use10msPacing() and Use20msPacing(). Similarly, you can add a 500ms delay after sending the HOTP with AppendDelayToOtp().
You can also add additional keystrokes as needed for your intended application with SendTabFirst() (sends a tab before the HOTP characters) and AppendCarriageReturn() ( sends an Enter key after the HOTP has been sent to a device).
For a full list of the methods in the ConfigureHotp class, please see the API documentation.
For an example of how to use ConfigureHotp(), please see How to program a slot with an OATH HOTP credential.