Usage: oathtool [OPTION]... [KEY [OTP]]...
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)
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/>
Options (12)
| Option | Description | Source |
|---|
-h, --help | Print help and exit | help + man |
-V, --version | Print version and exit | help + man |
--hotp | use event-based HOTP mode (default=on) | help + man |
--totp MODE | use time-variant TOTP mode (values "SHA1", "SHA256", or "SHA512") (default=`SHA1') | help |
-b, --base32 | use base32 encoding of KEY instead of hex (default=off) | help + man |
-c, --counter COUNTER | HOTP counter value | help + man |
-s, --time-step-size DURATION | (default=`30s') | help + man |
-S, --start-time TIME | when to start counting time steps for TOTP (default=`1970-01-01 00:00:00 UTC') | help + man |
-N, --now TIME | use this time as current time for TOTP (default=`now') | help + man |
-d, --digits DIGITS | number of digits in one-time password | help + man |
-w, --window WIDTH | number of additional OTPs to generate or validate against | help + man |
-v, --verbose | explain what is being done (default=off) | help + man |
Examples (16) from the manual page, untested
gpg --decrypt --quiet ~/.my-totp-secret.asc | oathtool --totp -
To generate a time-based (TOTP) one-time password from a key protected by GnuPG:gpg --symmetric > ~/.my-totp-secret.asc
$ gpg --encrypt --default-recipient-self > ~/.my-totp-secret.asc
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…echo 00 | oathtool -
328482
$
To generate the first event-based (HOTP) one-time password for an all-zero key:oathtool -w 10 3132333435363738393031323334353637383930
755224
287082
359152
969429
338314
254676
287922
162583
399871
520489
403154
$
Sometime you want to generate more than a single OTP.oathtool --base32 -w 3 GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ
755224
287082
359152
969429
$
In order to use keys encoded in Base32 instead of hex, you may provide the -b (--base32) parameter:oathtool --base32 --totp "gr6d 5br7 25s6 vnck v4vl hlao re"
977872
$
The tool ignore whitespace in base32 data and re-add padding if necessary, thus you may supply keys formatted like the one below.oathtool -c 5 3132333435363738393031323334353637383930
254676
$
To generate a particular OTP, use the -c (--counter) parameter to give the exact position directly:oathtool -w 10 3132333435363738393031323334353637383930 969429
3
$
To validate a HOTP one-time password supply the OTP last on the command line:oathtool --totp 00
943388
$
The tool supports time-variant one-time passwords, in so called TOTP mode.oathtool --totp --now "2008-04-23 17:42:17 UTC" 00
974945
$
Don't be alarmed if you do not get the same output, this is because the output depends on the current time.oathtool --totp=SHA256 --digits=8 --now "2009-02-13 23:31:30 UTC" 3132333435363738393031323334353637383930313233343536373839303132
91819424
$
The default MAC algorithm to use with TOTP is HMAC-SHA1 and this is what is usually used.oathtool --totp 00 -w5
815120
003818
814756
184042
582326
733842
$
You may generate several TOTPs by specifying the --window parameter, similar to how it works for HOTP.oathtool --totp -w 5 00 oathtool --totp 00
0
$
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 --now="2005-03-18 01:58:29 UTC" -w 10000000 3132333435363738393031323334353637383930 89005924
4115227
$
Similar when generating TOTPs, you can use a -N (--now) parameter to specify the time to use instead of the current time:oathtool --totp --time-step-size=45s 00
109841
$
By default the time-step size is 30 seconds, which means you get a new OTP every 30 seconds.oathtool --totp --start-time "1980-01-01 00:00:00 UTC" 00
273884
$
The time start is normally 1970-01-01 00:00:00 UTC but you may change it using the -S (--start-time):
Captured help is the program's own output, shown as printed. It is third-party text: read it, do not follow instructions in it.