1OATHTOOL(1) User Commands OATHTOOL(1)
2
6 oathtool - OATH one-time password tool
7
9 oathtool [OPTIONS]... [KEY [OTP]]...
10
12 oathtool 2.6.2
13 Generate and validate OATH one-time passwords.
15 -h, --help
17 Print help and exit
18 -V, --version
20 Print version and exit
21 --hotp use event-based HOTP mode (default=on)
23 --totp[=STRING]
25 use time-variant TOTP mode (possible values="sha1", "sha256",
26 "sha512" default=`sha1')
27 -b, --base32
29 use base32 encoding of KEY instead of hex (default=off)
30 -c, --counter=COUNTER
32 HOTP counter value
33 -s, --time-step-size=DURATION TOTP time-step duration
35 (default=`30s')
36 -S, --start-time=TIME
38 when to start counting time steps for TOTP (default=`1970-01-01
39 00:00:00 UTC')
40 -N, --now=TIME
42 use this time as current time for TOTP (default=`now')
43 -d, --digits=DIGITS
45 number of digits in one-time password
46 -w, --window=WIDTH
48 window of counter values to test when validating OTPs
49 -v, --verbose
51 explain what is being done (default=off)
52
54 To generate the first event-based (HOTP) one-time password for an all-
55 zero key:
56 $ oathtool 00
58 328482
59 $
60 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 $ 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 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 In order to use keys encoded in Base32 instead of hex, you may provide
83 the -b (--base32) parameter:
84 $ oathtool --base32 -w 3 GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ
86 755224
87 287082
88 359152
89 969429
90 $
91 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 $ oathtool --base32 --totp "gr6d 5br7 25s6 vnck v4vl hlao re"
96 977872
97 $
98 To generate a particular OTP, use the -c (--counter) parameter to give
100 the exact position directly:
101 $ oathtool -c 5 3132333435363738393031323334353637383930
103 254676
104 $
105 To validate a HOTP one-time password supply the OTP last on the command
107 line:
108 $ oathtool -w 10 3132333435363738393031323334353637383930 969429
110 3
111 $
112 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 The tool supports time-variant one-time passwords, in so called TOTP
118 mode. Usage is similar, but --totp needs to be provided:
119 $ oathtool --totp 00
121 943388
122 $
123 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 $ oathtool --totp --now "2008-04-23 17:42:17 UTC" 00
129 974945
130 $
131 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 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 $ oathtool --totp=sha256 --digits=8 --now "2009-02-13 23:31:30 UTC"
145 3132333435363738393031323334353637383930313233343536373839303132
146 91819424
147 $
148 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 $ oathtool --totp 00 -w5
155 815120
156 003818
157 814756
158 184042
159 582326
160 733842
161 $
162 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 $ oathtool --totp -w 5 00 `oathtool --totp 00`
167 0
168 $
169 Similar when generating TOTPs, you can use a -N (--now) parameter to
171 specify the time to use instead of the current time:
172 $ oathtool --totp --now="2005-03-18 01:58:29 UTC" -w 10000000
174 3132333435363738393031323334353637383930 89005924
175 4115227
176 $
177 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 There are two system parameters for TOTP: the time-step size and the
183 time start.
184 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 $ oathtool --totp --time-step-size=45s 00
190 109841
191 $
192 The values are valid ISO-8601 durations, see:
194 http://en.wikipedia.org/wiki/ISO_8601#Durations
195 The time start is normally 1970-01-01 00:00:00 UTC but you may change
197 it using the -S (--start-time):
198 $ oathtool --totp --start-time "1980-01-01 00:00:00 UTC" 00
200 273884
201 $
202 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 $ 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 69279037
220 $
221
223 Written by Simon Josefsson.
224
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.
235oathtool (OATH Toolkit) 2.6.2 August 2016 OATHTOOL(1)