[OATH-toolkit-help] Tutorial: oathtool

[Simon Josefsson]

To get you started using OATH Toolkit, the command line tool 'oathtool'
is a simple way.  After building and installing OATH Toolkit (download
the source code, do ./configure && make instal), you should have
'oathtool' in your PATH.  Read on for usage examples.

To generate the first event-based (HOTP) one-time password for an
all-zero key:

          $ oathtool 00
          328482
          $

To generate the first 10 event-based one-time passwords using the same
secret key which is used in the examples of RFC 4226 use the -w (--win‐
dow) parameter:

          $ oathtool -w 10 3132333435363738393031323334353637383930
          755224
          287082
          359152
          969429
          338314
          254676
          287922
          162583
          399871
          520489
          403154
          $

In the last output, the counter for the first OTP was 0, the second OTP
had a counter of 1, and so on.

To generate a particular OTP, use the -c (--counter) parameter to give
the exact position directly:

          $ oathtool -c 5 3132333435363738393031323334353637383930
          254676
          $

To validate a HOTP one-time password supply the OTP last on the command
line:

          $ oathtool -w 10 3132333435363738393031323334353637383930 969429
          3
          $

The output indicates the counter that was used.  It works by starting
with counter 0 and increment until it founds a match (or not), within
the supplied window of 10 OTPs.

The tool supports time-variant one-time passwords, in so called TOTP
mode.  Usage is similar, but --totp needs to be provided:

          $ oathtool --totp 00
          943388
          $

Don't be alarmed if you do not get the same output, this is because the
output is time variant.  To generate a TOTP for a particular fixed time
use the -N (--now) parameter:

          $ oathtool --totp --now "2008-04-23 17:42:17 UTC" 00
          974945
          $

The format is a mostly free format human readable date string such as
"Sun, 29 Feb 2004 16:21:42 -0800" or "2004-02-29 16:21:42" or even "next
Thursday".  It is the same used as the --date parameter of the date(1)
tool.

There are two systems parameter for TOTP: the time-step size and the
time start.

By default the time-step size is 30 seconds, which means you get a new
OTP every 30 seconds.  You may modify this with the -s
(--time-step-size) parameter:

          $ oathtool --totp --time-step-size=45s 00
          109841
          $

The values are valid ISO-8601 durations, see:
http://en.wikipedia.org/wiki/ISO_8601#Durations

The time start is normally 1970-01-01 00:00:00 UTC but you may change it
using the -S (--start-time):

          $ oathtool --totp --start-time "1980-01-01 00:00:00 UTC" 00
          273884
          $

To get more information about what the tool is using use the -v
(--verbose) parameter.  Finally, to generate the last TOTP (for SHA-1)
in the test vector table of draft-mraihi-totp-timebased-07 you can
invoke the tool like this:

          $  oathtool --totp -v -N "2033-05-18 03:33:20 UTC" -d8 
3132333435363738393031323334353637383930
          Hex secret: 3132333435363738393031323334353637383930
          Digits: 8
          Window size: 0
          Step size (seconds): 30
          Start time: 1970-01-01 00:00:00 UTC (0)
          Time now: 2033-05-18 03:33:20 UTC (2000000000)
          Counter: 0x3F940AA (66666666)

          69279037
          $

/Simon