1OATHTOOL(1) User Commands OATHTOOL(1)
2
6 oathtool - Open AuTHentication (OATH) one-time password tool
7
9 oathtool [OPTIONS]... [KEY [OTP]]...
10
12 oathtool 2.6.7
13 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 -h, --help
20 Print help and exit
21 -V, --version
23 Print version and exit
24 --hotp use event-based HOTP mode (default=on)
26 --totp[=MODE]
28 use time-variant TOTP mode (values "SHA1", "SHA256", or
29 "SHA512") (default=`SHA1')
30 -b, --base32
32 use base32 encoding of KEY instead of hex (default=off)
33 -c, --counter=COUNTER
35 HOTP counter value
36 -s, --time-step-size=DURATION TOTP time-step duration
38 (default=`30s')
39 -S, --start-time=TIME
41 when to start counting time steps for TOTP (default=`1970-01-01
42 00:00:00 UTC')
43 -N, --now=TIME
45 use this time as current time for TOTP (default=`now')
46 -d, --digits=DIGITS
48 number of digits in one-time password
49 -w, --window=WIDTH
51 number of additional OTPs to generate or validate against
52 -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 $ gpg --decrypt --quiet ~/.my-totp-secret.asc | oathtool --totp -
61 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 $ gpg --symmetric > ~/.my-totp-secret.asc
69 $ gpg --encrypt --default-recipient-self > ~/.my-totp-secret.asc
70 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 To generate the first event-based (HOTP) one-time password for an all-
77 zero key:
78 $ echo 00 | oathtool -
80 328482
81 $
82 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 $ 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 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 In order to use keys encoded in Base32 instead of hex, you may provide
105 the -b (--base32) parameter:
106 $ oathtool --base32 -w 3 GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ
108 755224
109 287082
110 359152
111 969429
112 $
113 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 $ oathtool --base32 --totp "gr6d 5br7 25s6 vnck v4vl hlao re"
118 977872
119 $
120 To generate a particular OTP, use the -c (--counter) parameter to give
122 the exact position directly:
123 $ oathtool -c 5 3132333435363738393031323334353637383930
125 254676
126 $
127 To validate a HOTP one-time password supply the OTP last on the command
129 line:
130 $ oathtool -w 10 3132333435363738393031323334353637383930 969429
132 3
133 $
134 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 The tool supports time-variant one-time passwords, in so called TOTP
140 mode. Usage is similar, but --totp needs to be provided:
141 $ oathtool --totp 00
143 943388
144 $
145 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 $ oathtool --totp --now "2008-04-23 17:42:17 UTC" 00
151 974945
152 $
153 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 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 $ oathtool --totp=SHA256 --digits=8 --now "2009-02-13 23:31:30 UTC"
167 3132333435363738393031323334353637383930313233343536373839303132
168 91819424
169 $
170 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 $ oathtool --totp 00 -w5
177 815120
178 003818
179 814756
180 184042
181 582326
182 733842
183 $
184 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 $ oathtool --totp -w 5 00 `oathtool --totp 00`
189 0
190 $
191 Similar when generating TOTPs, you can use a -N (--now) parameter to
193 specify the time to use instead of the current time:
194 $ oathtool --totp --now="2005-03-18 01:58:29 UTC" -w 10000000
196 3132333435363738393031323334353637383930 89005924
197 4115227
198 $
199 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 There are two system parameters for TOTP: the time-step size and the
205 time start.
206 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 $ oathtool --totp --time-step-size=45s 00
212 109841
213 $
214 The values are valid ISO-8601 durations, see:
216 http://en.wikipedia.org/wiki/ISO_8601#Durations
217 The time start is normally 1970-01-01 00:00:00 UTC but you may change
219 it using the -S (--start-time):
220 $ oathtool --totp --start-time "1980-01-01 00:00:00 UTC" 00
222 273884
223 $
224 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 $ 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 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.
257oathtool (OATH Toolkit) 2.6.7 May 2021 OATHTOOL(1)