Table of Contents Table of contents: Radiator® AAA Server <AuthBy SQLHOTP> 3.89 - <AuthBy SQLHOTP> <AuthBy SQLAUTHBY> 3.91 - <AuthBy SQLAUTHBY>

3.90. <AuthBy SQLTOTP>

This module supports authentication using TOTP (RFC 6238) authentication. TOTP is an open specification for time-based one-time passwords, developed by OATH Opens in new window
TOTP is a time-based authentication protocol, and is designed for use in 2 factor tokens and other similar authentication processes. It uses well-known SHA-1, SHA-256 or SHA-512 hash functions, along with a secret key and a timestamp. The specification is completely open and free and is the result of community collaboration with OATH.
The <AuthBy SQLTOTP> 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 TOTP one-time password.
The secret key, PIN 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.
Tip
Correct operation of time based authentication tokens such as TOTP requires accurate synchronisation of the clocks on the client and Radiator server computers.
<AuthBy SQLTOTP> supports by default PAP, EAP-TOP and EAP-GTC. CHAP, MSCHAP and MSCHAPv2 are supported but need to be enabled with AuthenProto configuration parameter. EAP-MSCHAP-V2 is supported as MSCHAPv2 when ConvertedFromEAPMSCHAPV2 is enabled. The CHAP methods do not support detection of bad PIN values.
Static passwords can be stored in an encrypted format when PAP, EAP-OTP or EAP-GTC is used. For more information about encrypted formats, see Section 7.1.2. Encrypted-Password
<AuthBy SQLTOTP> 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.90.1. AuthSelect

AuthSelect is an SQL query that fetches TOTP 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
The following fields are optional:
  • If field 1 (active) is defined, it must be 1 or other true value, else the authentication is rejected. Empty and 0 are false.
  • Field 2 (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 3 (digits) is the number of digits in the user's TOTP code. If NULL, the value of DefaultDigits is be used.
  • Field 4 (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 5 (last_time_accessed) is the unix timestamp of the last authentication attempt. It is used to detect brute force attacks.
  • Field 6 is the last TOTP timestep validated, which should be updated automatically by UpdateQuery.
  • Optional field 7 (algorithm) is the SHA algorithm which defaults to SHA-1 if the value is NULL or empty or has an unknown value. Possible values are SHA1, SHA256 and SHA512.
  • Optional field 8 (timestep) is the user's time step which defaults to the TimeStep configuration parameter if the value is 0 or NULL.
  • Optional field 9 (timestep_ origin) is the Unix epoch time of the first time step which defaults to TimeStepOrigin configuration parameter if the value is NULL.
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/totp.sql. The default is:
select secret, active, pin, digits, bad_logins, unix_timestamp(accessed),
last_timestep from totpkeys where username=%0

3.90.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.90.3. UpdateQuery

UpdateQuery is an SQL query that updates the TOTP token data in the SQL database. After a successful or failed authentication it will be passed the bad login count in %0, the user name in %1 and last TOTP timestep in %2. The default works with the sample database schema provided in goodies/totp.sql. The default is:
update totpkeys set accessed=now(), bad_logins=%0, last_timestamp=%2
where username=%1

3.90.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.90.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.90.6. EncryptedPIN

This parameter must be set if PIN, also known as static password, is stored in one of the encrypted formats Radiator supports. Encrypted PIN works only with PAP, EAP-OTP and EAP-GTC because these allow Radiator to check the PIN and TOTP code separately.
For more information about encrypted formats, see Section 7.1.2. Encrypted-Password.
# We use PAP, EAP-OTP or EAP-GTC and can use encrypted PIN
EncryptedPIN

3.90.7. 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.90.8. 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.

3.90.9. BadLoginWindow

Period of time in seconds that the user will be locked out after MaxBadLogins have occurred.

3.90.10. DelayWindow

DelayWindow is the maximum number of timeslots transmission delay that can be permitted between the client and server. Defaults to 1, the value recommended by the TOTP specification.

3.90.11. TimeStep

TimeStep is the size of the time step in seconds to use if the user record does not define time step. Defaults to 30 seconds, the value recommended by the TOTP specification.

3.90.12. TimeStepOrigin

TimeStepOrigin the Unix epoch time of the first time step to use if the user record does not define the origin. Defaults to 0 seconds (Jan 1, 1970), the value recommended by the TOTP specification.
Table of Contents Table of contents: Radiator® AAA Server <AuthBy SQLHOTP> 3.89 - <AuthBy SQLHOTP> <AuthBy SQLAUTHBY> 3.91 - <AuthBy SQLAUTHBY>