NAME
   Net::Radius::PacketOrdered - interface to RADIUS packets with proxy
   states

SYNOPSIS
     use Net::Radius::PacketOrdered;
     use Net::Radius::Dictionary;

     my $d = new Net::Radius::Dictionary "/etc/radius/dictionary";

     my $p = new Net::Radius::PacketOrdered $d, $data;
     $p->dump;

     if ($p->attr('User-Name' eq "lwall") {
       my $resp = new Net::Radius::PacketOrdered $d;
       $resp->set_code('Access-Accept');
       $resp->set_identifier($p->identifier);
       $resp->set_authenticator($p->authenticator);
       $resp->set_attr('Reply-Message' => "Welcome, Larry!\r\n");
       my $respdat = auth_resp($resp->pack, "mysecret");
       ...

DESCRIPTION
   RADIUS (RFC2865) specifies a binary packet format which contains various
   values and attributes. Net::Radius::PacketOrdered provides an interface
   to turn RADIUS packets into Perl data structures and vice-versa.

   Net::Radius::PacketOrdered does not provide functions for obtaining
   RADIUS packets from the network. A simple network RADIUS server is
   provided as an example at the end of this document.

 Proxy-State, RFC specification
   from RFC 2865 - ftp://ftp.rfc-editor.org/in-notes/rfc2865.txt

   2. Operation

   If any Proxy-State attributes were present in the Access-Request, they
   MUST be copied unmodified and in order into the response packet. Other
   Attributes can be placed before, after, or even between the Proxy-State
   attributes.

   2.3 Proxy

   The forwarding server MUST treat any Proxy-State attributes already in
   the packet as opaque data. Its operation MUST NOT depend on the content
   of Proxy-State attributes added by previous servers.

   If there are any Proxy-State attributes in the request received from the
   client, the forwarding server MUST include those Proxy-State attributes
   in its reply to the client. The forwarding server MAY include the
   Proxy-State attributes in the access-request when it forwards the
   request, or MAY omit them in the forwarded request. If the forwarding
   server omits the Proxy-State attributes in the forwarded access-request,
   it MUST attach them to the response before sending it to the client.

 Proxy-State, Implementation
   Proxy-State attributes are stored in an array, and when copied from one
   Net::Radius::PacketOrdered to another - using method *new* with packet
   data as attribute - they retain their order.

   *attr* method always returns last attribute inserted.

   *set_attr* method pushed name attribute onto the Attributes stack, or
   overwrites it in specific circumnstances, as described in method
   documentation.

 PACKAGE METHODS
   *new* Net::Radius::PacketOrdered $dictionary, $data
       Returns a new Net::Radius::PacketOrdered object. $dictionary is an
       optional reference to a Net::Radius::Dictionary object. If not
       supplied, you must call set_dict. If $data is supplied, unpack will
       be called for you to initialize the object.

 OBJECT METHODS
   There are actually two families of object methods. The ones described
   below deal with standard RADIUS attributes. An additional set of methods
   handle the Vendor-Specific attributes as defined in the RADIUS protocol.
   Those methods behave in much the same way as the ones below with the
   exception that the prefix *vs* must be applied before the *attr* in most
   of the names. The vendor code must also be included as the first
   parameter of the call.

   The *vsattr* and *set_vsattr* methods, used to query and set
   Vendor-Specific attributes return an array reference with the values of
   each instance of the particular attribute in the packet. This difference
   is required to support multiple VSAs with different parameters in the
   same packet.

   ->*set_dict*($dictionary)
       Net::Radius::PacketOrdered needs access to a Net::Radius::Dictionary
       object to do packing and unpacking. set_dict must be called with an
       appropriate dictionary reference (see Net::Radius::Dictionary)
       before you can use ->pack or ->unpack.

   ->*code*
       Returns the Code field as a string. As of this writing, the
       following codes are defined:

               Access-Request          Access-Accept
               Access-Reject           Accounting-Request
               Accounting-Response     Access-Challenge
               Status-Server           Status-Client

   -><set_code>($code)
       Sets the Code field to the string supplied.

   ->*identifier*
       Returns the one-byte Identifier used to match requests with
       responses, as a character value.

   ->*set_identifier*
       Sets the Identifier byte to the character supplied.

   ->*authenticator*
       Returns the 16-byte Authenticator field as a character string.

   ->*set_authenticator*
       Sets the Authenticator field to the character string supplied.

   ->*set_attr*($name, $val, $rewrite_flag)
       Sets the named Attributes to the given value. Values should be
       supplied as they would be returned from the attr method. If
       rewrite_flag is set, and a single attribute with such name already
       exists on the Attributes stack, its value will be overwriten with
       the supplied one. In all other cases (if there are more than one
       attributes with such name already on the stack, there are no
       attributes with such name, rewrite_flag is omitted) name/pair array
       will be pushed onto the stack.

   ->*attributes*
       Retrieves a list of attribute names present within the packet.

   ->*attr*($name)
       Retrieves the value of the named Attribute. If there are multiple
       values for the Attribute, last one inserted will be returned. This
       is behaviour is crucial for correct implementation of Proxy-State.

   ->*unset_attr*($name,$value)
       Removes given Attribute with given value from the Attributes stack.

   ->*attr_slot*($integer)
       Retrieves the attribute value of the given slot number from the
       Attributes stack.

   ->*unset_attr_slot*($integer)
       Removes given stack position from the Attributes stack.

   ->*password*($secret)
       The RADIUS User-Password attribute is encoded with a shared secret.
       Use this method to return the decoded version. This also works when
       the attribute name is 'Password' for compatibility reasons.

   ->*set_password*($passwd, $secret)
       The RADIUS User-Password attribute is encoded with a shared secret.
       Use this method to prepare the encoded version. Note that this
       method always stores the encrypted password in the 'User-Password'
       attribute. Some servers have been reported on insisting on this
       attribute to be 'Password' instead.

   ->*show_unknown_entries($bool)*
       Controls the generation of a "warn()" whenever an unknown tuple is
       seen.

   ->*acct_request_auth*($packet, $secret)
       Set request authenticator in binary packet, for accounting request
       authentication.

   ->*acct_response_auth*($packet, $secret, request-auth)
       Set reponse authenticator in binary packet, for accounting response
       authentication.

   ->*dump*
       Prints the content of the packet to STDOUT.

   ->*pack*
       Returns a raw RADIUS packet suitable for sending to a RADIUS client
       or server.

   ->*unpack*($data)
       Given a raw RADIUS packet $data, unpacks its contents so that they
       can be retrieved with the other methods (code, attr, etc.).

 EXPORTED SUBROUTINES
   *auth_resp*($packed_packet, $secret)
       Given a (packed) RADIUS packet and a shared secret, returns a new
       packet with the Authenticator field changed in accordace with RADIUS
       protocol requirements.

NOTES
   This document is (not yet) intended to be a complete description of how
   to implement a RADIUS server. Please see the RFCs (at
   ftp://ftp.livingston.com/pub/radius/) for that. The following is a brief
   description of the procedure:

     1. Receive a RADIUS request from the network.
     2. Unpack it using this package.
     3. Examine the attributes to determine the appropriate response.
     4. Construct a response packet using this package.
        Copy the Identifier and Authenticator fields from the request,
        set the Code as appropriate, and fill in whatever Attributes
        you wish to convey in to the server.
     5. Call the pack method and use the auth_resp function to
        authenticate it with your shared secret.
     6. Send the response back over the network.
     7. Lather, rinse, repeat.

EXAMPLE
       #!/usr/local/bin/perl -w

       use Net::Radius::Dictionary;
       use Net::Radius::PacketOrdered;
       use Net::Inet;
       use Net::UDP;
       use Fcntl;
       use strict;

       # This is a VERY simple RADIUS authentication server which responds
       # to Access-Request packets with Access-Accept.  This allows anyone
       # to log in.

       my $secret = "mysecret";  # Shared secret on the term server

       # Parse the RADIUS dictionary file (must have dictionary in current dir)
       my $dict = new Net::Radius::Dictionary "dictionary"
         or die "Couldn't read dictionary: $!";

       # Set up the network socket (must have radius in /etc/services)
       my $s = new Net::UDP { thisservice => "radius" } or die $!;
       $s->bind or die "Couldn't bind: $!";
       $s->fcntl(F_SETFL, $s->fcntl(F_GETFL,0) | O_NONBLOCK)
         or die "Couldn't make socket non-blocking: $!";

       # Loop forever, recieving packets and replying to them
       while (1) {
         my ($rec, $whence);
         # Wait for a packet
         my $nfound = $s->select(1, 0, 1, undef);
         if ($nfound > 0) {
           # Get the data
           $rec = $s->recv(undef, undef, $whence);
           # Unpack it
           my $p = new Net::Radius::PacketOrdered $dict, $rec;
           if ($p->code eq 'Access-Request') {
             # Print some details about the incoming request (try ->dump here)
             print $p->attr('User-Name'), " logging in with password ",
                   $p->password($secret), "\n";
             # Create a response packet
             my $rp = new Net::Radius::PacketOrdered $dict;
             $rp->set_code('Access-Accept');
             $rp->set_identifier($p->identifier);
             $rp->set_authenticator($p->authenticator);
             # (No attributes are needed.. but you could set IP addr, etc. here)
             # Authenticate with the secret and send to the server.
             $s->sendto(auth_resp($rp->pack, $secret), $whence);
           }
           else {
             # It's not an Access-Request
             print "Unexpected packet type recieved.";
             $p->dump;
           }
         }
       }

RADIUS PROXY EXAMPLE
   See README.proxy for how to setup a test consisting of radius client,
   server and multiple proxies inbetween, all using this module and
   FreeRadius. Scripts for all components (client/server/proxies) in the
   test setup are provided in the CPAN distribution of the module.

   About the stability, this code has been in very active use since early
   2004 on a network with 8000+ edge devices without a single problem
   encountered so far. It has been succesfully used under FreeBSD and
   Linux.

AUTHOR
   Christopher Masto, <[email protected]>. VSA support by Luis E. Mu�oz,
   <[email protected]>. Fix for unpacking 3COM VSAs contributed by Ian
   Smith <[email protected]>. Information for packing of 3Com VSAs
   provided by Quan Choi <[email protected]>. Some functions contributed
   by Tony Mountifield <[email protected]>.

   Extension of Net:Radius::Packet into Net:Radius::PacketOrdered to
   include the ability to implement correctly Proxy-State by Toni Prug,
   <[email protected]>, idea by Bill Hulley.

COPYRIGHT
   Original work (c) Christopher Masto. Changes (c) 2002,2003 Luis E. Mu�oz
   <[email protected]>. PacketOrdered changes (c) 2004 Toni Prug. All
   rights reserved.

   This package is free software and is provided "as is" without express or
   implied warranty. It may be used, redistributed and/or modified under
   the same terms as Perl itself.

   See <http://www.perl.com/perl/misc/Artistic.html>

SEE ALSO
   Net::Radius::Dictionary Net::Radius::Packet

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.