xenial (1) oathtool.1.gz

Provided by: oathtool_2.6.1-1_amd64 bug

NAME

       oathtool - OATH one-time password tool

SYNOPSIS

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

DESCRIPTION

       oathtool 2.6.1

       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[=STRING]
              use time-variant TOTP mode  (possible values="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
              (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
          $

       Sometime  you  want  to  generate more than a single OTP.  To generate 10 additional event-based one-time
       passwords, with the secret key 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  up
       to 10.

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

          $ oathtool --base32 -w 3 GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ
          755224
          287082
          359152
          969429
          $

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

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

       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  depends  on  the  current
       time.  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.

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

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

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

          $ oathtool --totp 00 -w5
          815120
          003818
          814756
          184042
          582326
          733842
          $

       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
          Base32 secret: GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ
          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   ©   2015   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.