Share this post:
IBM Verify – TOTP screen
One-time passwords (OTP) are widely used as a 2nd factor to add an additional layer of security to your account’s login. IBM Verify and the SDK support the generation of time-based (TOTP) and hash-based one-time passwords (HOTP) for SHA1, SHA256 and SHA512.
Despite that its configuration is considered as “easy”, it can be time-consuming to identify the reason if the generated password on server and client site don’t match. This article provides you guidance on troubleshooting that.
Common xOTP issues
- One of the most common issues for TOTPs is, that the clock on server and client side are out of sync. The period for updating a TOTP is usually 30 seconds. Therefore, it is not sufficient that client and server clocks are synchronized to the same minute – they must not exceed a few (< 3) seconds. This can be easily achieved by using a Network Time Protocol (NTP) server to synchronize the clocks.
- Another TOTP specific issue can be the timezone setting. The default to start counting the time steps is unix time T0, which is 00:00:00, 01. Jan 1970 UTC – the important part here is UTC. Even if your device shows the correct time for your location, but the timezone setting is wrong, the device will calculate a false UTC time, based on these settings. The result is a TOTP for a different point in time.
- The latter is especially relevant if you travel with your device across different time-zones. Depending on its configuration, time and time-zone settings are automatically updated by your mobile provider. Make sure to configure it correctly if you do it manually.
- HOTPs don’t have these timing issues. However, once they got out of sync, it can be really cumbersome to bring client and server together again. The HOTP standard describes a way to re-synchronize the counter by considering a window of e.g. the next 3 HOTPs and compare those against the value received from the client.
The OATH toolkit (don’t confused it with OAuth) by the Initiative for Open Authentication, is a library that implements HOTP and TOTP and it comes with a command line tool called
oathtool that provides a convenient way to call that library.
The installation for MacOs requires Homebrew (skip this if you have it already installed):
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" < /dev/null 2> /dev/null
brew install oath-toolkit
Binaries for other OS and the source code can be found here.
Generate a HOTP with secret 1234:
$ oathtool 1234
The same for TOTP:
$ oathtool --totp 1234
TOTP, but with a different algorithm (default is HMAC-SHA1):
$ oathtool --totp=sha256 1234
The -w (–window) parameter calculates the one-time passwords for additional counters. This is particularly useful to identify time sync issue.
$ oathtool --totp=sha256 -w 10 1234
Use a base32 encoded secret:
$ oathtool --totp=sha256 -w 5 --base32 GEZDGNA
$ oathtool --totp=sha256 -w 5 --time-step-size=42 --base32 GEZDGNA
For a different point in time:
$ oathtool --totp=sha256 -w 5 --time-step-size=42 --base32 GEZDGNA --now="2019-01-01 00:00:00 UTC"
$ oathtool --totp=sha256 -v --time-step-size=42 --base32 GEZDGNA --now="2019-01-01 00:00:00 UTC"
Hex secret: 31323334
Base32 secret: GEZDGNA=
Window size: 0
Step size (seconds): 42
Start time: 1970-01-01 00:00:00 UTC (0)
Current time: 2019-01-01 00:00:00 UTC (1546300800)
Counter: 0x231C72D (36816685)
The manual of the OATH tool describes these parameters more in detail.