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

NAME

6       oathtool - Open AuTHentication (OATH) one-time password tool
7

SYNOPSIS

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

DESCRIPTION

12       oathtool 2.6.7
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

EXAMPLES

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

AUTHOR

245       Written by Simon Josefsson.
246

REPORTING BUGS

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.7      May 2021                        OATHTOOL(1)
Impressum