OATHTOOL(1)

NAME
oathtool - OATH one-time password tool

SYNOPSIS
oathtool [OPTIONS]... [KEY [OTP]]...

DESCRIPTION
oathtool 1.6.2

Generate and validate OATH one-time passwords.

-h, --help
    Print help and exit

-V, --version
    Print version and exit

--hotp
    use event-based HOTP mode (default=on)

--totp
    use time-variant TOTP mode (default=off)

-c, --counter=COUNTER
    HOTP counter value

-s, --time-step-size=DURATION TOTP time-step duration
    (default=`30s')

-S, --start-time=TIME
    when to start counting time steps for TOTP (default=`1970-01-01 00:00:00 UTC')

-N, --now=TIME
    use this time as current time for TOTP (default=`now')

-d, --digits=DIGITS
    number of digits in one-time password

-w, --window=WIDTH
    window of counter values to test when validating OTPs

-v, --verbose
    explain what is being done (default=off)

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 (--window) 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. You can validate a TOTP one-time password by supplying the secret and a window parameter (number of time steps before or after current time):
   $ oathtool --totp -w 5 00 `oathtool --totp 00`
   0
   $ Similar when generating TOTPs, you can use a -N (--now) parameter to specify the time to use instead of the current time:
  $ oathtool --totp --now="2005-03-18 01:58:29 UTC" -w 10000000 3132333435363738393031323334353637383930 89005924
  4115227
  $ The previous test uses values from the TOTP specification and will stress test the tool because the expected window is around 4 million time-steps. There are two system parameters 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
   $

AUTHOR
Written by Simon Josefsson.

REPORTING BUGS
Report bugs to: oath-toolkit-help@nongnu.org oathtool home page: <http://www.nongnu.org/oath-toolkit/>
General help using GNU software: <http://www.gnu.org/gethelp/>

COPYRIGHT
Copyright © 2011 Simon Josefsson. License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.