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
 

1. 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.
2. 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.
3. 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 telecommunication provider. Make sure to configure it correctly if you do it manually.
4. 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.

Tools

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.

Installation

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

and then:

brew install oath-toolkit

Binaries for other OS and the source code can be found here.

Usage

Generate a HOTP with secret 1234:

$ oathtool 1234
376439

The same for TOTP:

$ oathtool --totp 1234
087756

TOTP, but with a different algorithm (default is HMAC-SHA1):

$ oathtool --totp=sha256 1234
787634

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
787634
885016
008235
773801
037367
810324
930766
439333
257583
539815
267801

Use a base32 encoded secret:

$ oathtool --totp=sha256 -w 5 --base32 GEZDGNA
074312
348365
881930
341776
594313

Different period:

$ oathtool --totp=sha256 -w 5 --time-step-size=42 --base32 GEZDGNA
128324
153768
665196
472063
124992
185500

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"
759395
477025
397995
070419
104372
957315

Verbose output:

$ oathtool --totp=sha256 -v --time-step-size=42 --base32 GEZDGNA --now="2019-01-01 00:00:00 UTC"
Hex secret: 31323334
Base32 secret: GEZDGNA=
Digits: 6
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)
759395

The manual of the OATH tool describes these parameters more in detail.

[Update 24.04.2020]
In vary rare circumstances it could even be possible that the time, provided by the telecommunication provider is out of sync. That would calculate the wrong OTP, even you have turned on the time-sync feature on your phone. To verify that you can:

1. Check the time against https://greenwichmeantime.com/
2. Use the -w flag of the OATH tool to calculate OTP for a longer period of time - but make sure your laptop has the correct time set.