Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
OATHTOOL(1)			 User Commands			   OATHTOOL(1)

NAME
       oathtool	- Open AuTHentication (OATH) one-time password tool

SYNOPSIS
       oathtool	[OPTION]... [KEY [OTP]]...

DESCRIPTION
       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 sys-
       tems).

       -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	neces-
       sary, 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 particu-
       lar 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 (--ver-
       bose) 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-2023	Simon Josefsson.  License GPLv3+: GNU GPL ver-
       sion 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.

OATH Toolkit 2.6.9		   July	2023			   OATHTOOL(1)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=oathtool&sektion=1&manpath=FreeBSD+Ports+14.3.quarterly>

home | help