Section 3.89. <AuthBy SQLHOTP>

3.89. <AuthBy SQLHOTP>

This module supports authentication using HOTP (RFC 4226) authentication. HOTP is an open specification for event-based one-time passwords, developed by OATH

HOTP is an event-based authentication protocol, and is designed for use in 2 factor tokens and other similar authentication processes. It uses the well-known SHA-1 hash function, along with a secret key and an incrementing counter. The specification is completely open and free and is the result of community collaboration with OATH.

The <AuthBy SQLHOTP> authentication module detects replay and brute-force attacks. It supports optional PIN, also known as static password, for 2 factor authentication when the user prefixes their static password before the HOTP one-time password.

The secret key, current counter and other information are stored in a SQL database. Any database supported by Radiator can be used. A sample configuration file and SQL schema for MySQL are supplied in the goodies/ directory of your Radiator distribution.

<AuthBy SQLHOTP> supports the same parameters as <AuthBy xxxxxx>. For more information, see Section 3.32. <AuthBy xxxxxx>. It supports also all the common SQL configuration parameters. For more information about the SQL configuration parameters, see Section 3.8. SQL configuration.

3.89.1. AuthSelect

AuthSelect is an SQL query that fetches HOTP token data from the SQL database. AuthSelect is expected to return a number of fields that describe the token.

The following fields are mandatory:

Field 0 is the HEX encoded secret key for the token
Field 1 is the counter high part
Field 2 is the counter low part

The following fields are optional:

If field 3 (active) is defined, it must be 1 or other true value, else the authentication is rejected. Empty and 0 are false.
Field 4 (pin) is the user's static PIN. It will be checked if the user specifies a static password or if Require2Factor is not set to disabled.
Field 5 (digits) is the number of digits in the user's HOTP code. If NULL, the value of DefaultDigits is be used.
Field 6 (bad_logins) counts the number of consecutive authentication failures. If defined it will be used to detect brute force attacks and must be updated by UpdateQuery.
Field 7 (last_time_accessed) is the unix timestamp of the last authentication attempt. It is used to detect brute force attacks.

Current username is available as %0 which is SQL quoted when used in AuthSelect and unmodified when used with AuthSelectParam.

The default works with the sample database schema provided in goodies/hotp.sql. The default is:

select secret, counter_high, counter_low, active, pin, digits,
bad_logins, unix_timestamp(accessed) from hotpkeys where username=%0

3.89.2. AuthSelectParam

This optional parameter specifies a bind variable to be used with AuthSelect. See Section 3.8.1. SQL bind variables for information about how to use bind variables.

3.89.3. UpdateQuery

UpdateQuery is an SQL query that updates the HOTP token data in the SQL database. After a successful or failed authentication it will be passed the new authentication counter high in %0, new authentication counter low in %1, bad login count in %2, the user name in %3, The default works with the sample database schema provided in goodies/hotp.sql.

%0 and the other formatters are SQL quoted, if needed, when used in UpdateQuery and unmodified when used with UpdateQueryParam.

The default UpdateQuery is:

update hotpkeys set accessed=now(), counter_high=%0, counter_low=%1,
bad_logins=%2 where username=%3

3.89.4. UpdateQueryParam

This optional parameter specifies a bind variable to be used with UpdateQuery. See Section 3.8.1. SQL bind variables for information about how to use bind variables.

3.89.5. Require2Factor

If flag parameter Require2Factor is not set to disabled, then the user must provide their static password as a prefix to their one-time password. The correct static password is returned by AuthSelect. If the user provides a static password prefix, then the static password is always checked regardless of Require2Factor setting.

3.89.6. DefaultDigits

DefaultDigits specifies the number of one-time password digits to use if the user record does not define digits. Defaults to 6. Minimum allowed is 4.

3.89.7. MaxBadLogins

MaxBadLogins specifies how many consecutive bad PINs or bad OTP codes will be tolerated in the last BadLoginWindow seconds. If more than MaxBadLogins bad authentication attempts occurs and if the last one is within the last BadLoginWindow seconds, the authentication attempt will be rejected. The user must wait at least BadLoginWindow seconds before attempting to authenticate again. MaxBadLogins defaults to 10.

Attempt counter and window information is maintained in SQL with UpdateQuery and AuthSelect.