resynctool - Manual resync tool for event-based HOTP tokens
resynctool -1 otp1 -2 otp2 [options]
- -1 otp1 first OTP otp1
- -2 otp2 second OTP otp2
- -u user emit state for user user
- -k key use key key
- -c challenge set initial counter value from challenge
- -i counter initial counter value to test
- -f counter final counter value to test
- -d debug switch
Event-based tokens generate an OTP by using an event counter as input to the OTP algorithm. The event counter is incremented on each use of the token.
Unlike time-based tokens, event-based tokens can get out of sync with the server due to network issues or misuse. The rwindow_size setting in /etc/otpd.conf is used to search over a larger range of event counter values (starting from the last known good counter) than normal, and can be used to overcome sync problems to some extent, but it is not advised to set it very large as it creates more work for the server, and therefore with "severe" sync problems the user may become effectively locked out.
When using LDAP with otpd, a user-specific rwindow_size setting can be made, which allows the user to self-resync.
When using files with otpd, user-specific settings are not available, and therefore resynctool is provided. Some sites may want to use it with LDAP as well.
To use resynctool, give the username, token key and two consecutive freshly generated OTPs. resynctool will output the state data which will resync the user. Suggested usage (wrap this in a script):
resynctool -u USER -k ... -1 123456 -2 123456 >/dev/null &&
resynctool -u USER -k ... -1 123456 -2 123456 >/etc/otpstate/USERresynctool is designed to work with any event-based HOTP token which uses a counter that increments by one for each subsequent use of the token. Because RFC 4226 does not specify how the counter should be derived, resynctool may not work with all tokens.
- -1 otp1
-
The first of two consecutive OTPs.
- -2 otp2
-
The second of two consecutive OTPs.
- -u user
-
The user that holds the token; it is necessary for the state data. If not provided, a generic value will be used which must then be replaced with the actual username, otherwise otpd will not consider the state to be valid.
- -k key
-
The token secret.
- -c challenge
-
The last known good challenge (hex counter) value. It is an 8 octet value (16 hex digits), stored as the third field of v5 state. Using this option tells resynctool to begin searching for candidate event counters at this value instead of at 0. This saves work testing event counters that cannot possibly be valid. To extract the challenge value (work this into your wrapper script):
cut -d: -f3 /etc/otpstate/USER
- -i counter
-
This is an alternative to the -c option. Instead of a hex value, this option takes a decimal counter.
- -f counter
-
The final (decimal) counter value to test. By default, resynctool will test 65536 values before giving up. If the first character of counter is
+(plus), instead of using counter as an absolute value it will be added to the initial value. - -d
-
Activate debug output (eg: the counters)
otpd(8), RFC 4226