1OATHTOOL(1)                      User Commands                     OATHTOOL(1)
2
3
4

NAME

6       oathtool - OATH one-time password tool
7

SYNOPSIS

9       oathtool [OPTIONS]... [KEY [OTP]]...
10

DESCRIPTION

12       oathtool 2.6.2
13
14       Generate and validate OATH one-time passwords.
15
16       -h, --help
17              Print help and exit
18
19       -V, --version
20              Print version and exit
21
22       --hotp use event-based HOTP mode  (default=on)
23
24       --totp[=STRING]
25              use  time-variant  TOTP mode  (possible values="sha1", "sha256",
26              "sha512" default=`sha1')
27
28       -b, --base32
29              use base32 encoding of KEY instead of hex (default=off)
30
31       -c, --counter=COUNTER
32              HOTP counter value
33
34       -s, --time-step-size=DURATION TOTP time-step duration
35              (default=`30s')
36
37       -S, --start-time=TIME
38              when to start counting time steps for TOTP  (default=`1970-01-01
39              00:00:00 UTC')
40
41       -N, --now=TIME
42              use this time as current time for TOTP (default=`now')
43
44       -d, --digits=DIGITS
45              number of digits in one-time password
46
47       -w, --window=WIDTH
48              window of counter values to test when validating OTPs
49
50       -v, --verbose
51              explain what is being done  (default=off)
52

EXAMPLES

54       To  generate the first event-based (HOTP) one-time password for an all-
55       zero key:
56
57          $ oathtool 00
58          328482
59          $
60
61       Sometime you want to generate more than a single OTP.  To  generate  10
62       additional  event-based one-time passwords, with the secret key used in
63       the examples of RFC 4226, use the -w (--window) parameter:
64
65          $ oathtool -w 10 3132333435363738393031323334353637383930
66          755224
67          287082
68          359152
69          969429
70          338314
71          254676
72          287922
73          162583
74          399871
75          520489
76          403154
77          $
78
79       In the last output, the counter for the first OTP was 0, the second OTP
80       had a counter of 1, and so on up to 10.
81
82       In  order to use keys encoded in Base32 instead of hex, you may provide
83       the -b (--base32) parameter:
84
85          $ oathtool --base32 -w 3 GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ
86          755224
87          287082
88          359152
89          969429
90          $
91
92       The tool ignore whitespace in base32 data and re-add padding if  neces‐
93       sary, thus you may supply keys formatted like the one below.
94
95          $ oathtool --base32 --totp "gr6d 5br7 25s6 vnck v4vl hlao re"
96          977872
97          $
98
99       To  generate a particular OTP, use the -c (--counter) parameter to give
100       the exact position directly:
101
102          $ oathtool -c 5 3132333435363738393031323334353637383930
103          254676
104          $
105
106       To validate a HOTP one-time password supply the OTP last on the command
107       line:
108
109          $ oathtool -w 10 3132333435363738393031323334353637383930 969429
110          3
111          $
112
113       The  output  indicates the counter that was used.  It works by starting
114       with counter 0 and increment until it founds a match (or  not),  within
115       the supplied window of 10 OTPs.
116
117       The  tool  supports  time-variant one-time passwords, in so called TOTP
118       mode.  Usage is similar, but --totp needs to be provided:
119
120          $ oathtool --totp 00
121          943388
122          $
123
124       Don't be alarmed if you do not get the same output, this is because the
125       output  depends on the current time.  To generate a TOTP for a particu‐
126       lar fixed time use the -N (--now) parameter:
127
128          $ oathtool --totp --now "2008-04-23 17:42:17 UTC" 00
129          974945
130          $
131
132       The format is a mostly free format human readable date string  such  as
133       "Sun,  29  Feb  2004  16:21:42  -0800" or "2004-02-29 16:21:42" or even
134       "next Thursday".  It is the same used as the --date  parameter  of  the
135       date(1) tool.
136
137       The  default  MAC  algorithm  to use with TOTP is HMAC-SHA1 and this is
138       what is usually used.  The tool supports two  other  MACs,  namely  the
139       HMAC-SHA256  and  HMAC-SHA512 as well.  To use either of these, qualify
140       the --totp parameter with a value.  Use "sha256"  for  HMAC-SHA256  and
141       "sha512"  for HMAC-SHA512.  The following demonstrate generating one of
142       the RFC 6238 test vectors.
143
144          $ oathtool --totp=sha256 --digits=8 --now "2009-02-13 23:31:30  UTC"
145       3132333435363738393031323334353637383930313233343536373839303132
146          91819424
147          $
148
149       You  may  generate  several TOTPs by specifying the --window parameter,
150       similar to how it works for HOTP.  The OTPs generated here will be  for
151       the  initial  time (normally current time) and then each following time
152       step (e.g., 30 second window).
153
154          $ oathtool --totp 00 -w5
155          815120
156          003818
157          814756
158          184042
159          582326
160          733842
161          $
162
163       You can validate a TOTP one-time password by supplying the secret and a
164       window parameter (number of time steps before or after current time):
165
166          $ oathtool --totp -w 5 00 `oathtool --totp 00`
167          0
168          $
169
170       Similar  when  generating  TOTPs, you can use a -N (--now) parameter to
171       specify the time to use instead of the current time:
172
173         $  oathtool  --totp  --now="2005-03-18  01:58:29  UTC"  -w   10000000
174       3132333435363738393031323334353637383930 89005924
175         4115227
176         $
177
178       The  previous  test  uses  values  from the TOTP specification and will
179       stress test the tool because the expected window is  around  4  million
180       time-steps.
181
182       There  are  two  system parameters for TOTP: the time-step size and the
183       time start.
184
185       By default the time-step size is 30 seconds, which means you get a  new
186       OTP   every   30   seconds.    You   may   modify   this  with  the  -s
187       (--time-step-size) parameter:
188
189          $ oathtool --totp --time-step-size=45s 00
190          109841
191          $
192
193       The     values     are     valid     ISO-8601      durations,      see:
194       http://en.wikipedia.org/wiki/ISO_8601#Durations
195
196       The  time  start is normally 1970-01-01 00:00:00 UTC but you may change
197       it using the -S (--start-time):
198
199          $ oathtool --totp --start-time "1980-01-01 00:00:00 UTC" 00
200          273884
201          $
202
203       To get more information about what the tool is using use the -v (--ver‐
204       bose) parameter.  Finally, to generate the last TOTP (for SHA-1) in the
205       test vector table of draft-mraihi-totp-timebased-07 you can invoke  the
206       tool like this:
207
208          $   oathtool   --totp   -v   -N   "2033-05-18   03:33:20   UTC"  -d8
209       3132333435363738393031323334353637383930
210          Hex secret: 3132333435363738393031323334353637383930
211          Base32 secret: GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ
212          Digits: 8
213          Window size: 0
214          Step size (seconds): 30
215          Start time: 1970-01-01 00:00:00 UTC (0)
216          Time now: 2033-05-18 03:33:20 UTC (2000000000)
217          Counter: 0x3F940AA (66666666)
218
219          69279037
220          $
221

AUTHOR

223       Written by Simon Josefsson.
224

REPORTING BUGS

226       Report  bugs  to:  oath-toolkit-help@nongnu.org  oathtool  home   page:
227       <http://www.nongnu.org/oath-toolkit/>
228       General help using GNU software: <http://www.gnu.org/gethelp/>
229
231       Copyright © 2016 Simon Josefsson.  License GPLv3+: GNU GPL version 3 or
232       later <http://gnu.org/licenses/gpl.html>.
233       This is free software: you are free  to  change  and  redistribute  it.
234       There is NO WARRANTY, to the extent permitted by law.
235
236
237
238oathtool (OATH Toolkit) 2.6.2     August 2016                      OATHTOOL(1)
Impressum