Provided by: libnet-radius-perl_2.103+dfsg-1_all bug

NAME

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

SYNOPSIS

         use Net::Radius::Packet;
         use Net::Radius::Dictionary;

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

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

         if ($p->attr('User-Name' eq "lwall") {
           my $resp = new Net::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");
           ...

         die "Packet is a fake response\n" if ($p->code eq 'Access-Accept'
           and not auth_req_verify($data, $secret, $req->authenticator))

         die "Packet is a fake\n" if ($p->code eq 'Accounting-Request'
           and not auth_acct_verify($data, $secret))

DESCRIPTION

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

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

   PACKAGE METHODS
       new Net::Radius::Packet $dictionary, $data
           Returns a new Net::Radius::Packet 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.

   Proxy-State, RFC specification
       From RFC-2865:

         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
       "->pack()" and "->dump()" now work properly with multiple atributes, in particular the
       Proxy-State attribute - This means that the packet will be encoded with the multiple
       attributes present. This change makes Net::Radius::PacketOrdered likely redundant.

       "->attr()" method always return the last attribute inserted.

       "->set_attr()" and "->set_vsattr()" methods push either the attribute or the vendor-
       specific attribute, onto the Attributes stack, or overwrites it in specific
       circumnstances, as described in method documentation. The "->unset_attr()" and
       "->unset_vsattr()" perform the opposite function.

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

       ->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
               Accounting-Status
               Interim-Accounting
               Password-Request
               Password-Ack
               Password-Reject
               Accounting-Message
               Access-Challenge
               Status-Server
               Status-Client
               Resource-Free-Request
               Resource-Free-Response
               Resource-Query-Request
               Resource-Query-Response
               Alternate-Resource-Reclaim-Request
               NAS-Reboot-Request
               NAS-Reboot-Response
               Next-Passcode
               New-Pin
               Terminate-Session
               Password-Expired
               Event-Request
               Event-Response
               Disconnect-Request
               Disconnect-ACK
               Disconnect-NAK
               CoA-Request
               CoA-ACK
               CoA-NAK
               IP-Address-Allocate
               IP-Address-Release

       ->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($id)
           Sets the Identifier byte to the character supplied.

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

       ->set_authenticator($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

           The following types are simply mapped to other types until correct encoding is
           implemented:

           ipv6addr
               Treated as a string

           date
               Treated as a string

           ifid
               Treated as a string

           When multiple attributes are inserted in the packet, the last one is returned.

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

       ->set_vsattr($vendor, $name, $val, $rewrite_flag)
           Analogous to "->set_attr()", but operates on vendor-specific attributes for vendor
           $vendor.

       ->unset_attr($name)
           Sets the named Attribute to the given value.  Values should be supplied as they would
           be returned from the attr method.

       ->unset_vsattr($vendor, $name)
           Analogous to "->unset_attr()", but operates on vendor-specific attributes for vendor
           $vendor.

       ->attr_slot($integer)
           Deprecated synonym for "->attr_slot_val()".

       ->attr_slots()
           Return the number of attribute slots in the packet.

       ->attr_slot_name($integer)
           Retrieves the attribute name of the given slot number from the Attributes stack.
           Returns undef when the slot is vacant.

       ->attr_slot_val($integer)
           Retrieves the attribute value of the given slot number from the Attributes stack.
           Returns undef when the slot is vacant.

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

       ->password($secret, [$attr])
           The RADIUS User-Password attribute is encoded with a shared secret.  Use this method
           to return the decoded version. By default, the password will be looked for in the
           User-Password attribute. You can specify an alternate RADIUS attribute, by using the
           second argument.

       ->set_password($passwd, $secret, [$attribute])
           The RADIUS User-Password attribute is encoded with a shared secret.  Use this method
           to prepare the encoded version. The encoded password will be stored in the attribute
           $attribute, which defaults to 'User-Password'.

           Some servers have been reported on insisting on this attribute to be 'Password'
           instead. You may have to tweak this call or the dictionary accordingly.

       ->dump()
           Prints the content of the packet to STDOUT.

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

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

           If the third optional parameter is true, the Authenticator is encoded for an
           accounting packet, using 16 0x0 octets as the placeholder for the authenticator.

       auth_acct_verify($packet, $secret)
           Verifies the authenticator in an Accounting-Request packet as explained in RFC-2866.
           Returns 1 if the authenticator matches the packet and the secret, undef otherwise.

           $packet is the packet data, as received. $secret is the corresponding shared secret.

       auth_req_verify($packet, $secret, $prev_auth)
           Verifies the authenticator in Access-Accept, Access-Reject, and Access-Challenge
           packets as explained in RFC-2865. Returns 1 if the authenticator matches the packet
           and the secret, undef otherwise.

           $packet is the packet data, as received. $secret is the corresponding shared secret.
           $prev_auth is the authenticator taken from the corresponding Access-Accept packet.

           It's the application's job to keep track of the authenticators in each request.

EXAMPLE

       See the examples included in the examples/ directory of the distribution. Also see
       Net::Radius::Server(3) for a more complete implementation of a RADIUS server.

AUTHOR

       Christopher Masto, <chris@netmonger.net>. VSA support by Luis E. Mun~oz,
       <luismunoz@cpan.org>. Fix for unpacking 3COM VSAs contributed by Ian Smith
       <iansmith@ncinter.net>. Information for packing of 3Com VSAs provided by Quan Choi
       <Quan_Choi@3com.com>. Some functions contributed by Tony Mountifield
       <tony@mountifield.org>. Attribute ordering provided by Toni Prug, <toni@irational.org>,
       idea by Bill Hulley.

SEE ALSO

       Perl, Net::Radius::Server(3), Net::Radius::Dictionary(3), RFCs 2865, 2866, 2882 and 3575.