auth.texi

gnu 的radius服务器很好用的

retrieving the information about open sessions and, optionally, a
query to close an existing open record.

There are two queries for retrieving the information:
@code{mlc_user_query} returns the list of sessions opened by the user,
@code{mlc_realm_query} returns the list of sessions opened for the
given realm. Each of them should return a list of 5-element
tuples@footnote{This interface is likely to change in future versions}:

@smallexample
@var{user-name}, @var{nas-ip-address}, @var{nas-port-id}, @var{acct-session-id}
@end smallexample

Here is an example of @code{mlc_user_query} and @code{mlc_realm_query}:

@smallexample     
mlc_user_query SELECT user_name,nas_ip_address,\
                      nas_port_id,acct_session_id \
               FROM calls \
               WHERE user_name='%C@{User-Name@}' \
               AND status = 1

mlc_realm_query SELECT user_name,nas_ip_address,\
                       nas_port_id,acct_session_id \
                FROM calls \
                WHERE realm_name='%C@{Realm-Name@}'     
@end smallexample

Apart from these two queries you may also wish to provide a query for
closing a hung record. By default, @command{radiusd} will use
@code{acct_stop_query}. If you wish to override it, supply a query
named @code{mlc_stop_query}, for example:

@smallexample
mlc_stop_query UPDATE calls \
               SET status=4,\
                acct_session_time=unix_timestamp(now())-\
                                  unix_timestamp(event_date_time) \
               WHERE user_name='%C@{User-Name@}' \
                 AND status = 1 \
                 AND acct_session_id='%C@{Acct-Session-Id@}' 
@end smallexample

@xref{Queries}, for detailed information on how to write these queries.

@node Verifying Active Sessions
@subsection Verifying Active Sessions

Whatever database @command{radiusd} uses, an open entry in it does not
necessary mean that the corresponding session is still being
active. So, after retrieving the information about user sessions, 
Radius verifies on corresponding @NAS{}es whether these are actually
active.

For each entry in the session list, if its @NAS{} acknowledges the
session, the session count is incremented. Otherwise, such entry is
marked as closed in the database and is not counted.

There may also be cases when the @NAS{} is unreachable due to some
reasons. In such cases the Radius behavior is determined by the value
of @code{checkrad-assume-logged} in @file{config} file
@ref{auth,,auth statement (raddb/config)}. If the value is @code{yes},
Radius assumes the session is still active and increases the session
count, otherwise it proceeds as if the @NAS{} returned negative reply.

To query a @NAS{}, Radius first looks up its type and additional parameters
in @file{naslist} file (@pxref{naslist file}). There are two
predefined @NAS{} types that cause Radius to act immediately without
querying tne @NAS{}: the special type @samp{true} forces Radius to act
as if the @NAS{} returned 1, the type @samp{false} forces it to act
as if the @NAS{} returned 0. If the type is neither of this predefined types,
Radius uses it as a look up key into the @file{nastypes} file
(@pxref{nastypes file}) and tries to retrieve an entry which has
matching type. If such entry does not exist, Radius issues the error
message and acts accordingly to the value of configuration variable
@code{checkrad-assume-logged}. Otherwise, Radius determines the query
method to use from the second field of this entry, and constructs method
arguments by appending arguments from the @file{naslist} entry to
those of @code{nastypes} entry. Note, that the former take precedence over the
latter, and can thus be used to override default values specified
in @file{nastypes}.

Having determined the query method and its argument, Radius queries
@NAS{} and analyzes its output by invoking a user-supplied
Rewrite function. The function to use
is specified by the @code{function=} argument to the method. It is
called each time a line of output is received from the @NAS{} (for
finger queries) or a variable is received (for SNMP queries). The
process continues until the function returns 1 or the last line
of output is read or a timeout occurs whichever comes first.

If the user-function returns 1 it is taken to mean the user's session is
now active at the @NAS{}, otherwise, if it replies 0 or if the end of
output is reached, it is taken to mean the user's session is not active.

The syntax conventions for user-supplied functions are described in
detail in @ref{Login Verification Functions}.

@comment *L2****************************************************************
@node Auth Probing
@section Controlling Authentication Probes
@cindex Controlling Authentication Probes
@cindex authentication probes

@dfn{Authentication probe} is an attempt of a user to use other user's
account, by guessing his password. The obvious indication of an
authentication probe is appearence of several consecutive
authentication failures for the same user. Of course, if the intruder
is given sufficient number of such probes he will sooner or later
succeed in finding the actual password. The conventional method
to prevent this from occurring is to keep @dfn{failure counters} for
each user and to lock the account when its failure countrer reaches a
predefined limit. Notice that a legitimate user may fail (sometimes
even several times in sequence) in entering his password so, two
important points should always be observed. First, failure counters
record the number of consecutive authentication failures and they are
reset after each successive authentication. Secondly, the maximum number
of allowed consecutive failures should be set sufficiantly high.

The version @value{VERSION} offers two ways for controlling 
authentication probes: using external programs and using special
@acronym{SQL} queries.

To control authentication probes using external programs, use the
combination of @attr{Exec-Program-Wait} and
@attr{Auth-Failure-Trigger}. The program specified by
@attr{Auth-Failure-Trigger} is executed each time an authentication
attempt failed. When both attributes are used together, the program
invoked by @attr{Auth-Failure-Trigger} can update the failure
counter, and the one invoked by @attr{Exec-Program-Wait} can compare
the counter value with the predefined limit and reject authentication
when both values become equal. Such approach is most useful in
conjunction with @code{BEGIN} profile.

Let's suppose the program @file{/sbin/check_failure} accepts a user name
and returns 1 if the failure counter for this user has reached maximum
allowed value. Otherwise it returns 0 and clears the counter. Another program,
@file{/sbin/count_failure} increases failure counter value for the
given user name. Assuming our basic authentication type is @samp{PAM},
the @file{raddb/users} file will look as follows:

@smallexample
@group
BEGIN   NULL
        Exec-Program-Wait = "/sbin/check_failure  %C@{User-Name@}",
        Auth-Failure-Trigger = "/sbin/count_failure %C@{User-Name@}",
                Fall-Through = Yes

DEFAULT Auth-Type = PAM
        Service-Type = Framed-User,
                Framed-Protocol = PPP

[@dots{} Other profiles @dots{}]                
@end group
@end smallexample

The @code{BEGIN} profile will be executed before any other profile.
It will add to the @RHS{} @attr{Exec-Program-Wait} and
@attr{Auth-Failure-Trigger} attributes and then @command{radiusd} will
proceed to finding a matching profile (due to @attr{Fall-Through}
attribute). When such profile is found, the user will be authenticated
according to the method set up by the profile's @attr{Auth-Type}
attribute. If authentication fails, @file{/sbin/count_failure}
will be called and the user name passed to it as the argument. Otherwise,
@file{/sbin/check_failure} will be invoked. 

To complete the example, here are working versions of both programs.
Failure counters for each user name are kept in separate file in 
@file{/var/log/radius/fails} directory. Both programs are written
in @command{bash}.

@subheading The /sbin/count_failure program

@smallexample
@group
#! /bin/bash

test $# -eq 1 || exit 1

MAXFAIL=8
REGDIR=/var/log/radius/fails

if [ -r "$REGDIR/$1" ]; then
  read COUNT < "$REGDIR/$1"
  COUNT=$((COUNT+1))
else
  COUNT=1
fi
echo $COUNT > "$REGDIR/$1"      
# End of /sbin/count_failure
@end group
@end smallexample

@subheading The /sbin/check_failure program

@smallexample
@group
#! /bin/bash

test $# -eq 1 || exit 1

MAXFAIL=8
REGDIR=/var/log/radius/fails

if [ -r "$REGDIR/$1" ]; then
  read COUNT < "$REGDIR/$1"
  if [ $COUNT -ge $MAXFAIL ]; then
    echo "Reply-Message=\"Too many login failures. Your account is locked\""
    exit 1
  else
    rm "$REGDIR/$1"
  fi
fi
exit 0

# End of check_failure
@end group
@end smallexample


Another way of controlling authentication probes is by using
@acronym{SQL} database to store failure counters. Two queries are
provided for this purpose in @file{raddb/sqlserver} file:
@code{auth_success_query} is executed upon each successful
authentication, and @code{auth_failure_query} is executed upon
each authentication failure. Both queries are not expected to return
any values. One obvious purpose of @code{auth_failure_query} would be to
update failure counters and that of @code{auth_success_query} would be
to clear them. The @code{auth_query} or @code{group_query} should then
be modified to take into account the number of authentication
failures.

The default @acronym{SQL} configuration GNU Radius is shipped with
provides a working example of using these queries. Let's consider this
example.

First, we create a special table for keeping authentication failure
counters for each user:

@smallexample
@group
CREATE TABLE authfail (
  # User name this entry refers to
  user_name           varchar(32) binary default '' not null,
  # Number of successive authentication failures for this user
  count               int,
  # Timestamp when this entry was last updated
  time                datetime DEFAULT '1970-01-01 00:00:00' NOT NULL,
  # Create a unique index on user_name
  UNIQUE uname (user_name)
);
@end group
@end smallexample

The query @code{auth_fail_query} will increment the value of
@code{count} column for the user in question:

@smallexample
@group
auth_failure_query UPDATE authfail \
                   SET count=count+1,time=now() \
                   WHERE user_name='%C@{User-Name@}'
@end group
@end smallexample

The query @code{auth_success_query} will clear @code{count}:

@smallexample
@group
auth_success_query UPDATE authfail \
                   SET count=0,time=now() \
                   WHERE user_name='%C@{User-Name@}'
@end group
@end smallexample

Now, the question is: how to use this counter in authentication? The
answer is quite simple. First, let's create a special group for all the
users whose authentication failure counter has reached its maximum
value. Let this group be called @samp{*LOCKED_ACCOUNT*}. We'll add the
following entry to @file{raddb/users}:

@smallexample
@group
DEFAULT Group = "*LOCKED_ACCOUNT*",
                Auth-Type = Reject
        Reply-Message = "Your account is currently locked.\n\
Please, contact your system administrator\n"
@end group
@end smallexample

@noindent
which will reject all such users with an appropriate reply message.

The only thing left now is to rewrite @code{group_query} so that it
returns @samp{*LOCKED_ACCOUNT*} when @code{authfail.count} reaches its
maximum value. Let's say this maximum value is 8. Then the following
query will do the job:


@smallexample
@group
group_query       SELECT user_group FROM groups \
                  WHERE user_name='%u' \
                  UNION \
                  SELECT CASE WHEN (SELECT count > 8 FROM authfail \
                                                 WHERE user_name='%u')
                         THEN '*LOCKED_ACCOUNT*' END
@end group
@end smallexample

The default configuration comes with these queries commented out. It
is up to you to uncomment them if you wish to use @acronym{SQL}-based
control over authentication failures.

Notice the following important points when using this approach:

@enumerate 1
@item Your @acronym{SQL} server must support @code{UNION}. Earlier
versions of @code{MySQL} lacked this support, so if you run
@code{MySQL} make sure you run a reasonably new version (at least
4.0.18).

@item Both @code{auth_failure_query} and @code{auth_success_query}
assume the database already contains an entry for each user. So,
when adding a new user to the database, make sure to insert
an appropriate record into @code{authfails} table, e.g.

@smallexample
INSERT INTO authfail VALUES('new-user',0,now());
@end smallexample
@end enumerate