3.62. <AuthBy OTP>

This module is extensible and customisable to support a range of One-Time-Password (OTP) schemes, including automatic password generation and sending of passwords through a back-channel such as SMS. AuthBy OTP is suitable for authenticating 802.1X Wired and Wireless access with custom one-time password and token card authentication systems.
The default behaviour of AuthBy OTP demonstrates how it can be used and tested, but it is not suitable for use in a production environment: it tells the user the correct password in the challenge. In almost all cases, you will need to develop at least your own ChallengeHook, and possible a VerifyHook to work with your local system. See goodies/otp.cfg for a sample configuration file.
In the most common use of AuthBy OTP, it will be configured to generate a random password (according to a configurable password pattern) and then send it to the user by SMS or some other channel. AuthBy OTP will then challenge the user to enter the correct password (after they have received it through the SMS system or whatever). In order to achieve this, you must configure at least the ChallengeHook to call some external program that will deliver the password to the user.
AuthBy OTP works with EAP-OTP (One-Time-Password), EAP-GTC (Generic-Token-Card) as well as standard RADIUS PAP. Caution: some clients may not handle OTP challenges very well. AuthBy OTP supports PAP in the following way: if the user attempts to log in with an empty (zero length) password, the ChallengeHook will be called and the challenge will be sent back to the client. This may result in a message for the user, but often does not, depending on the client on the users computer.
You can test AuthBy OTP with the following radpwtst commands:
# Conventional RADIUS PAP
radpwtst -noacct -interactive -password ''
# EAP-OTP authentication
radpwtst -noacct -eapotp
# EAP-GTC auth (with EAPType set to Generic-Token):
# radpwtst -noacct -eapgtc

3.62.1. ChallengeHook

ChallengeHook is a fragment of Perl code that is expected to generate a OTP (if necessary) save the OTP (in $context is sometimes convenient) and send the OTP to the user by a back channel (if necessary). It should return a challenge string that will be presented to the user by the client, informing them of how to get or generate their password.
It is passed the following arguments:
  • Reference to the current AuthBy module object
  • User name
  • Current RADIUS request packet
  • User context that will be available later in VerifyHook. It can be used to store information such as the correct password until later in the authentication process.
The default ChallengeHook generates a random password according to PasswordPattern, saves it in the context and returns a challenge message telling the user what the correct password is. The default ChallengeHook must not be used in a production environment.
This example shows how to generate a random password and pass it to an external program which must deliver it to the user through some back channel like SMS. The example just echoes it to stdout. You can see that the generate_password() function can be used to generate a random password that conforms to PasswordPattern. The password is stored in the context so it can be checked later in the VerifyHook.
ChallengeHook sub {my ($self, $user, $p, $context) = @_;\
      $context->{otp_password} = $self->generate_password();\ 
      system('/bin/echo', "in sample ChallengeHook for", \
      $user, "password is", $context->{otp_password});\
      return "Your OTP password has been printed by Radiator on STDOUT";}

3.62.2. VerifyHook

VerifyHook is a fragment of Perl code that is expected to validate a OTP and return 1 on success. You will need to specify your own VerifyHook if you require an external program to verify the correct OTP.
VerifyHook is passed the following arguments:
  • Reference to the current AuthBy module object
  • User name
  • Submitted OTP password in plaintext
  • Current RADIUS request packet
  • Same user context that was passed to ChallengeHook for this user when the challenge was generated. $context->{otp_password} will generally contain the correct plaintext password for this user.
The default VerifyHook compares the submitted password to $context->{otp_password}.
This example VerifyHook only accepts the password 'xyzzy':
VerifyHook sub {my ($self,$user,$submitted_pw,$p,$context)=@_;\
return $context->{otp_password} eq 'xyzzy';}

3.62.3. PasswordPattern

This optional parameter specifies a character pattern that will be used to generate random passwords by generate_password() and the default ChallengeHook.
  • a
    Lowercase alphanumeric (abcdefghijklmnopqrstuvwxyz0123456789)
  • A
    Uppercase alphanumeric (ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789)
  • c
    lowercase consonant (bcdfghjklmnpqrstvwxyz)
  • C
    uppercase consonant (BCDFGHJKLMNPQRSTVWXYZ)
  • v
    lowercase vowel (aeiou)
  • V
    uppercase vowel (AEIOU)
  • 9
    numeric (0123456789)
  • anything else is used literally
The default is cvcvcvc99 which produces passwords like:

3.62.4. ContextTimeout

This optional parameter specifies how long (in seconds) the context passed to ChallengeHook for a user will be kept. It defaults to 120 seconds, which is expected to be enough time for most users to receive and enter their correct OTP. You should not need to change this.