oathtool(1) User Commands oathtool(1)
NAME
oathtool - Open AuTHentication (OATH) one-time password tool
SYNOPSIS
oathtool [OPTIONS]... [KEY [OTP]]...
DESCRIPTION
oathtool 2.6.7
Generate and validate OATH one-time passwords. KEY and OTP is the string
'-' to read from standard input, '@FILE' to read from indicated filename,
or a hex encoded value (not recommended on multi-user systems).
-h, --help
Print help and exit
-V, --version
Print version and exit
--hotp use event-based HOTP mode (default=on)
--totp[=MODE]
use time-variant TOTP mode (values "SHA1", "SHA256", or "SHA512")
(default=`SHA1')
-b, --base32
use base32 encoding of KEY instead of hex (default=off)
-c, --counter=COUNTER
HOTP counter value
-s, --time-step-size=DURATION TOTP time-step duration
(default=`30s')
-S, --start-time=TIME
when to start counting time steps for TOTP (default=`1970-01-01
00:00:00 UTC')
-N, --now=TIME
use this time as current time for TOTP (default=`now')
-d, --digits=DIGITS
number of digits in one-time password
-w, --window=WIDTH
number of additional OTPs to generate or validate against
-v, --verbose
explain what is being done (default=off)
EXAMPLES
To generate a time-based (TOTP) one-time password from a key protected by
GnuPG:
$ gpg --decrypt --quiet ~/.my-totp-secret.asc | oathtool --totp -
How to create the encrypted file is outside of scope of this manual, see
gpg(1), however the following two commands may help you to encrypt the
secret symmetrically (using a password) or asymmetrically (if you have
created a private key), respectively. You will need to provide the
secret from the terminal after invoking the commands.
$ gpg --symmetric > ~/.my-totp-secret.asc
$ gpg --encrypt --default-recipient-self > ~/.my-totp-secret.asc
For easier reading, the rest of this man page provides the KEY and OTP on
the command line. Keep in mind that this usage is not recommended since
on most multi-user systems, command-line parameters of running processes
can be seen by other users.
To generate the first event-based (HOTP) one-time password for an all-
zero key:
$ echo 00 | oathtool -
328482
$
Sometime you want to generate more than a single OTP. To generate 10
additional event-based one-time passwords, with the secret key used in
the examples of RFC 4226, use the -w (--window) parameter:
$ oathtool -w 10 3132333435363738393031323334353637383930
755224
287082
359152
969429
338314
254676
287922
162583
399871
520489
403154
$
In the last output, the counter for the first OTP was 0, the second OTP
had a counter of 1, and so on up to 10.
In order to use keys encoded in Base32 instead of hex, you may provide
the -b (--base32) parameter:
$ oathtool --base32 -w 3 GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ
755224
287082
359152
969429
$
The tool ignore whitespace in base32 data and re-add padding if
necessary, thus you may supply keys formatted like the one below.
$ oathtool --base32 --totp "gr6d 5br7 25s6 vnck v4vl hlao re"
977872
$
To generate a particular OTP, use the -c (--counter) parameter to give
the exact position directly:
$ oathtool -c 5 3132333435363738393031323334353637383930
254676
$
To validate a HOTP one-time password supply the OTP last on the command
line:
$ oathtool -w 10 3132333435363738393031323334353637383930 969429
3
$
The output indicates the counter that was used. It works by starting
with counter 0 and increment until it founds a match (or not), within the
supplied window of 10 OTPs.
The tool supports time-variant one-time passwords, in so called TOTP
mode. Usage is similar, but --totp needs to be provided:
$ oathtool --totp 00
943388
$
Don't be alarmed if you do not get the same output, this is because the
output depends on the current time. To generate a TOTP for a particular
fixed time use the -N (--now) parameter:
$ oathtool --totp --now "2008-04-23 17:42:17 UTC" 00
974945
$
The format is a mostly free format human readable date string such as
"Sun, 29 Feb 2004 16:21:42 -0800" or "2004-02-29 16:21:42" or even "next
Thursday". It is the same used as the --date parameter of the date(1)
tool.
The default MAC algorithm to use with TOTP is HMAC-SHA1 and this is what
is usually used. The tool supports two other MACs, namely the
HMAC-SHA256 and HMAC-SHA512 as well. To use either of these, qualify the
--totp parameter with a value. Use "SHA256" for HMAC-SHA256 and "SHA512"
for HMAC-SHA512. The following demonstrate generating one of the RFC
6238 test vectors.
$ oathtool --totp=SHA256 --digits=8 --now "2009-02-13 23:31:30 UTC"
3132333435363738393031323334353637383930313233343536373839303132
91819424
$
You may generate several TOTPs by specifying the --window parameter,
similar to how it works for HOTP. The OTPs generated here will be for
the initial time (normally current time) and then each following time
step (e.g., 30 second window).
$ oathtool --totp 00 -w5
815120
003818
814756
184042
582326
733842
$
You can validate a TOTP one-time password by supplying the secret and a
window parameter (number of time steps before or after current time):
$ oathtool --totp -w 5 00 `oathtool --totp 00`
0
$
Similar when generating TOTPs, you can use a -N (--now) parameter to
specify the time to use instead of the current time:
$ oathtool --totp --now="2005-03-18 01:58:29 UTC" -w 10000000
3132333435363738393031323334353637383930 89005924
4115227
$
The previous test uses values from the TOTP specification and will stress
test the tool because the expected window is around 4 million time-steps.
There are two system parameters for TOTP: the time-step size and the time
start.
By default the time-step size is 30 seconds, which means you get a new
OTP every 30 seconds. You may modify this with the -s (--time-step-size)
parameter:
$ oathtool --totp --time-step-size=45s 00
109841
$
The values are valid ISO-8601 durations, see:
http://en.wikipedia.org/wiki/ISO_8601#Durations
The time start is normally 1970-01-01 00:00:00 UTC but you may change it
using the -S (--start-time):
$ oathtool --totp --start-time "1980-01-01 00:00:00 UTC" 00
273884
$
To get more information about what the tool is using use the -v
(--verbose) parameter. Finally, to generate the last TOTP (for SHA-1) in
the test vector table of RFC 6238 you can invoke the tool like this:
$ oathtool --totp -v -N "2033-05-18 03:33:20 UTC" -d8
3132333435363738393031323334353637383930
Hex secret: 3132333435363738393031323334353637383930
Base32 secret: GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ
Digits: 8
Window size: 0
TOTP mode: SHA1
Step size (seconds): 30
Start time: 1970-01-01 00:00:00 UTC (0)
Time now: 2033-05-18 03:33:20 UTC (2000000000)
Counter: 0x3F940AA (66666666)
69279037
$
AUTHOR
Written by Simon Josefsson.
REPORTING BUGS
Report bugs to: oath-toolkit-help@nongnu.org oathtool home page:
<https://www.nongnu.org/oath-toolkit/>
General help using GNU software: <https://www.gnu.org/gethelp/>
COPYRIGHT
Copyright (C) 2009-2021 Simon Josefsson. License GPLv3+: GNU GPL version
3 or later <https://gnu.org/licenses/gpl.html>.
This is free software: you are free to change and redistribute it. There
is NO WARRANTY, to the extent permitted by law.
oathtool (OATH Toolkit) 2.6.7 May 2021 oathtool(1)
oath-toolkit 2.6.7 - Generated Sat May 6 05:58:51 CDT 2023