MAN page from CentOS 8 oathtool-2.6.2-4.el8.x86_64.rpm


Section: User Commands (1)
Updated: August 2016


oathtool - OATH one-time password tool 


oathtool[,OPTIONS/]... [,KEY /[,OTP/]]... 


oathtool 2.6.2

Generate and validate OATH one-time passwords.

-h, --help
Print help and exit
-V, --version
Print version and exit
use event-based HOTP mode (default=on)
use time-variant TOTP mode (possiblevalues="sha1", "sha256", "sha512"default=`sha1')
-b, --base32
use base32 encoding of KEY instead of hex(default=off)
-c, --counter=,COUNTER/
HOTP counter value
-s, --time-step-size=,DURATION/ TOTP time-step duration
-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 whenvalidating OTPs
-v, --verbose
explain what is being done (default=off)


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

   $ oathtool 00

Sometime you want to generate more than a single OTP. To generate 10additional event-based one-time passwords, with the secret key used inthe examples of RFC 4226, use the -w (--window) parameter:

   $ oathtool -w 10 3132333435363738393031323334353637383930

In the last output, the counter for the first OTP was 0, the secondOTP had a counter of 1, and so on up to 10.

In order to use keys encoded in Base32 instead of hex, you may providethe -b (--base32) parameter:

   $ oathtool --base32 -w 3 GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ

The tool ignore whitespace in base32 data and re-add padding ifnecessary, thus you may supply keys formatted like the one below.

   $ oathtool --base32 --totp "gr6d 5br7 25s6 vnck v4vl hlao re"

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

   $ oathtool -c 5 3132333435363738393031323334353637383930

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

   $ oathtool -w 10 3132333435363738393031323334353637383930 969429

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

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

   $ oathtool --totp 00

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

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

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 thedate(1) tool.

The default MAC algorithm to use with TOTP is HMAC-SHA1 and this iswhat is usually used. The tool supports two other MACs, namely theHMAC-SHA256 and HMAC-SHA512 as well. To use either of these,qualify the --totp parameter with a value. Use "sha256" forHMAC-SHA256 and "sha512" for HMAC-SHA512. The following demonstrategenerating one of the RFC 6238 test vectors.

   $ oathtool --totp=sha256 --digits=8 --now "2009-02-13 23:31:30 UTC" 3132333435363738393031323334353637383930313233343536373839303132

You may generate several TOTPs by specifying the --window parameter,similar to how it works for HOTP. The OTPs generated here will be forthe initial time (normally current time) and then each following timestep (e.g., 30 second window).

   $ oathtool --totp 00 -w5

You can validate a TOTP one-time password by supplying the secret anda window parameter (number of time steps before or after currenttime):

   $ oathtool --totp -w 5 00 `oathtool --totp 00`

Similar when generating TOTPs, you can use a -N (--now) parameterto specify the time to use instead of the current time:

  $ oathtool --totp --now="2005-03-18 01:58:29 UTC" -w 10000000 3132333435363738393031323334353637383930 89005924

The previous test uses values from the TOTP specification and willstress test the tool because the expected window is around 4 milliontime-steps.

There are two system parameters for TOTP: the time-step size and thetime start.

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

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

The values are valid ISO-8601 durations, see:

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

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

To get more information about what the tool is using use the -v(--verbose) parameter. Finally, to generate the last TOTP (forSHA-1) in the test vector table of draft-mraihi-totp-timebased-07you 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)



Written by Simon Josefsson. 


Report bugs to: oath-toolkit-helpAATTnongnu.orgoathtool home page: <>
General help using GNU software: <> 


Copyright © 2016 Simon Josefsson.License GPLv3+: GNU GPL version 3 or later <>.
This is free software: you are free to change and redistribute it.There is NO WARRANTY, to the extent permitted by law.




This document was created byman2html,using the manual pages.