File: oathtool.h2m

package info (click to toggle)
oath-toolkit 2.6.1-1.3
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, buster, sid
  • size: 20,924 kB
  • sloc: ansic: 54,713; sh: 13,738; yacc: 1,254; xml: 756; makefile: 353
file content (169 lines) | stat: -rw-r--r-- 5,105 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
Copyright (C) 2009-2015 Simon Josefsson.  Licensed under the GPLv3+.

[NAME]
oathtool \- OATH one-time password tool
[EXAMPLES]
To generate the first event-based (HOTP) one-time password for an all-zero key:

   $ oathtool 00
   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 draft\-mraihi\-totp\-timebased\-07
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
   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
   $