1OATHTOOL(1) User Commands OATHTOOL(1)
2
3
4
6 oathtool - Open AuTHentication (OATH) one-time password tool
7
9 oathtool [OPTIONS]... [KEY [OTP]]...
10
12 oathtool 2.6.6
13
14 Generate and validate OATH one-time passwords. KEY and OTP is the
15 string '-' to read from standard input, '@FILE' to read from indicated
16 filename, or a hex encoded value (not recommended on multi-user sys‐
17 tems).
18
19 -h, --help
20 Print help and exit
21
22 -V, --version
23 Print version and exit
24
25 --hotp use event-based HOTP mode (default=on)
26
27 --totp[=MODE]
28 use time-variant TOTP mode (values "SHA1", "SHA256", or
29 "SHA512") (default=`SHA1')
30
31 -b, --base32
32 use base32 encoding of KEY instead of hex (default=off)
33
34 -c, --counter=COUNTER
35 HOTP counter value
36
37 -s, --time-step-size=DURATION TOTP time-step duration
38 (default=`30s')
39
40 -S, --start-time=TIME
41 when to start counting time steps for TOTP (default=`1970-01-01
42 00:00:00 UTC')
43
44 -N, --now=TIME
45 use this time as current time for TOTP (default=`now')
46
47 -d, --digits=DIGITS
48 number of digits in one-time password
49
50 -w, --window=WIDTH
51 number of additional OTPs to generate or validate against
52
53 -v, --verbose
54 explain what is being done (default=off)
55
57 To generate a time-based (TOTP) one-time password from a key protected
58 by GnuPG:
59
60 $ gpg --decrypt --quiet ~/.my-totp-secret.asc | oathtool --totp -
61
62 How to create the encrypted file is outside of scope of this manual,
63 see gpg(1), however the following two commands may help you to encrypt
64 the secret symmetrically (using a password) or asymmetrically (if you
65 have created a private key), respectively. You will need to provide
66 the secret from the terminal after invoking the commands.
67
68 $ gpg --symmetric > ~/.my-totp-secret.asc
69 $ gpg --encrypt --default-recipient-self > ~/.my-totp-secret.asc
70
71 For easier reading, the rest of this man page provides the KEY and OTP
72 on the command line. Keep in mind that this usage is not recommended
73 since on most multi-user systems, command-line parameters of running
74 processes can be seen by other users.
75
76 To generate the first event-based (HOTP) one-time password for an all-
77 zero key:
78
79 $ echo 00 | oathtool -
80 328482
81 $
82
83 Sometime you want to generate more than a single OTP. To generate 10
84 additional event-based one-time passwords, with the secret key used in
85 the examples of RFC 4226, use the -w (--window) parameter:
86
87 $ oathtool -w 10 3132333435363738393031323334353637383930
88 755224
89 287082
90 359152
91 969429
92 338314
93 254676
94 287922
95 162583
96 399871
97 520489
98 403154
99 $
100
101 In the last output, the counter for the first OTP was 0, the second OTP
102 had a counter of 1, and so on up to 10.
103
104 In order to use keys encoded in Base32 instead of hex, you may provide
105 the -b (--base32) parameter:
106
107 $ oathtool --base32 -w 3 GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ
108 755224
109 287082
110 359152
111 969429
112 $
113
114 The tool ignore whitespace in base32 data and re-add padding if neces‐
115 sary, thus you may supply keys formatted like the one below.
116
117 $ oathtool --base32 --totp "gr6d 5br7 25s6 vnck v4vl hlao re"
118 977872
119 $
120
121 To generate a particular OTP, use the -c (--counter) parameter to give
122 the exact position directly:
123
124 $ oathtool -c 5 3132333435363738393031323334353637383930
125 254676
126 $
127
128 To validate a HOTP one-time password supply the OTP last on the command
129 line:
130
131 $ oathtool -w 10 3132333435363738393031323334353637383930 969429
132 3
133 $
134
135 The output indicates the counter that was used. It works by starting
136 with counter 0 and increment until it founds a match (or not), within
137 the supplied window of 10 OTPs.
138
139 The tool supports time-variant one-time passwords, in so called TOTP
140 mode. Usage is similar, but --totp needs to be provided:
141
142 $ oathtool --totp 00
143 943388
144 $
145
146 Don't be alarmed if you do not get the same output, this is because the
147 output depends on the current time. To generate a TOTP for a particu‐
148 lar fixed time use the -N (--now) parameter:
149
150 $ oathtool --totp --now "2008-04-23 17:42:17 UTC" 00
151 974945
152 $
153
154 The format is a mostly free format human readable date string such as
155 "Sun, 29 Feb 2004 16:21:42 -0800" or "2004-02-29 16:21:42" or even
156 "next Thursday". It is the same used as the --date parameter of the
157 date(1) tool.
158
159 The default MAC algorithm to use with TOTP is HMAC-SHA1 and this is
160 what is usually used. The tool supports two other MACs, namely the
161 HMAC-SHA256 and HMAC-SHA512 as well. To use either of these, qualify
162 the --totp parameter with a value. Use "SHA256" for HMAC-SHA256 and
163 "SHA512" for HMAC-SHA512. The following demonstrate generating one of
164 the RFC 6238 test vectors.
165
166 $ oathtool --totp=SHA256 --digits=8 --now "2009-02-13 23:31:30 UTC"
167 3132333435363738393031323334353637383930313233343536373839303132
168 91819424
169 $
170
171 You may generate several TOTPs by specifying the --window parameter,
172 similar to how it works for HOTP. The OTPs generated here will be for
173 the initial time (normally current time) and then each following time
174 step (e.g., 30 second window).
175
176 $ oathtool --totp 00 -w5
177 815120
178 003818
179 814756
180 184042
181 582326
182 733842
183 $
184
185 You can validate a TOTP one-time password by supplying the secret and a
186 window parameter (number of time steps before or after current time):
187
188 $ oathtool --totp -w 5 00 `oathtool --totp 00`
189 0
190 $
191
192 Similar when generating TOTPs, you can use a -N (--now) parameter to
193 specify the time to use instead of the current time:
194
195 $ oathtool --totp --now="2005-03-18 01:58:29 UTC" -w 10000000
196 3132333435363738393031323334353637383930 89005924
197 4115227
198 $
199
200 The previous test uses values from the TOTP specification and will
201 stress test the tool because the expected window is around 4 million
202 time-steps.
203
204 There are two system parameters for TOTP: the time-step size and the
205 time start.
206
207 By default the time-step size is 30 seconds, which means you get a new
208 OTP every 30 seconds. You may modify this with the -s
209 (--time-step-size) parameter:
210
211 $ oathtool --totp --time-step-size=45s 00
212 109841
213 $
214
215 The values are valid ISO-8601 durations, see:
216 http://en.wikipedia.org/wiki/ISO_8601#Durations
217
218 The time start is normally 1970-01-01 00:00:00 UTC but you may change
219 it using the -S (--start-time):
220
221 $ oathtool --totp --start-time "1980-01-01 00:00:00 UTC" 00
222 273884
223 $
224
225 To get more information about what the tool is using use the -v (--ver‐
226 bose) parameter. Finally, to generate the last TOTP (for SHA-1) in the
227 test vector table of RFC 6238 you can invoke the tool like this:
228
229 $ oathtool --totp -v -N "2033-05-18 03:33:20 UTC" -d8
230 3132333435363738393031323334353637383930
231 Hex secret: 3132333435363738393031323334353637383930
232 Base32 secret: GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ
233 Digits: 8
234 Window size: 0
235 TOTP mode: SHA1
236 Step size (seconds): 30
237 Start time: 1970-01-01 00:00:00 UTC (0)
238 Time now: 2033-05-18 03:33:20 UTC (2000000000)
239 Counter: 0x3F940AA (66666666)
240
241 69279037
242 $
243
245 Written by Simon Josefsson.
246
248 Report bugs to: oath-toolkit-help@nongnu.org oathtool home page:
249 <https://www.nongnu.org/oath-toolkit/>
250 General help using GNU software: <https://www.gnu.org/gethelp/>
251
253 Copyright © 2009-2021 Simon Josefsson. License GPLv3+: GNU GPL version
254 3 or later <https://gnu.org/licenses/gpl.html>.
255 This is free software: you are free to change and redistribute it.
256 There is NO WARRANTY, to the extent permitted by law.
257
258
259
260oathtool (OATH Toolkit) 2.6.6 January 2021 OATHTOOL(1)