NAME

RADIUS::Packet - Object-oriented Perl interface to RADIUS packets

SYNOPSIS

  use RADIUS::Packet;
  use RADIUS::Dictionary;

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

  my $p = new RADIUS::Packet $d, $data;
  $p->dump;

  if ($p->attr('User-Name' eq "lwall") {
    my $resp = new RADIUS::Packet $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 (RFC2138) specifies a binary packet format which contains various values and attributes. RADIUS::Packet provides an interface to turn RADIUS packets into Perl data structures and vice-versa.

RADIUS::Packet 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. Also, a RADIUS::Server module is under development which will simplify the interface.

PACKAGE METHODS

new RADIUS::Packet $dictionary, $data: Returns a new RADIUS::Packet object. $dictionary is an optional reference to a 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

->set_dict($dictionary)

RADIUS::Packet needs access to a RADIUS::Dictionary object to do packing and unpacking. set_dict must be called with an appropriate dictionary reference (see the RADIUS::Dictionary manpage) before you can use ->pack or ->unpack.

->unpack($data)

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

->pack

Returns a raw RADIUS packet suitable for sending to a RADIUS client or server.

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

->attr($name)

Retrieves the value of the named Attribute. Attributes will be converted automatically based on their dictionary type:

        STRING     Returned as a string.
        INTEGER    Returned as a Perl integer.
        IPADDR     Returned as a string (a.b.c.d)
        TIME       Returned as an integer

->set_attr($name, $val)

Sets the named Attribute to the given value. Values should be supplied as they would be returned from the attr method.

->password($secret)

The RADIUS Password attribute is encoded with a shared secret. Use this method to return the decoded version.

->dump

Prints the packet's contents to STDOUT.

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. Recieve 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 RADIUS::Dictionary;
    use RADIUS::Packet;
    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 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 RADIUS::Packet $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 RADIUS::Packet $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;
        }
      }
    }

AUTHOR

Christopher Masto, chris@netmonger.net