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