Authen::Radius - provide simple Radius client facilities

       Carl   Declerck   <carl@miskatonic.inbe.net>   -   original  design  Alexander  Kapitanenko  <kapitan  at
       portaone.com> and Andrew Zhilenko <andrew at portaone.com> - later modifications.

       PortaOne Development Team <perl-radius at portaone.com> is the current module's maintainer at CPAN.

perl v5.40.0                                       2024-11-15                                        Radius(3pm)

       new ( Host => HOST, Secret => SECRET [, TimeOut => TIMEOUT] [,Service => SERVICE] [, Debug => Bool] [,
       LocalAddr => hostname[:port]] [,Rfc3579MessageAuth => Bool] [,NodeList= NodeListArrayRef])
           Creates  &  returns a blessed reference to a Radius object, or undef on failure.  Error status may be
           retrieved with "Authen::Radius::get_error" (errorcode) or "Authen::Radius::strerror"  (verbose  error
           string).

           The  default  "Service" is "radius", the alternative is "radius-acct".  If you do not specify port in
           the "Host" as a "hostname:port", then port specified in your /etc/services will be used. If there  is
           nothing  there,  and  you  did not specify port either then default is 1812 for "radius" and 1813 for
           "radius-acct".

           Optional parameter "Debug" with a Perl "true" value turns on debugging (verbose mode).

           Optional parameter "LocalAddr" may contain local IP/host bind address from which RADIUS  packets  are
           sent.

           Optional  parameter  "Rfc3579MessageAuth"  with  a  Perl "true" value turns on generating of Message-
           Authenticator for  Access-Request  (RFC3579,  section  3.2).   The  Message-Authenticator  is  always
           generated for Status-Server packets.

           Optional  parameter  "NodeList" may contain a Perl reference to an array, containing a list of Radius
           Cluster nodes. Each nodes in the list can be specified using a hostname or IP (with an optional  port
           number),  i.e.  'radius1.mytel.com'  or  'radius.myhost.com:1812'.  Radius  Cluster contains a set of
           Radius servers, at any given moment of time only one server is considered to be "active" (so requests
           are send to this server).  How the active node is determined? Initially in addition to the "NodeList"
           parameter you may supply the "Host" parameter and specify which server should become the first active
           node. If this parameter is absent, or the current active node does not reply anymore, the process  of
           "discovery"  will be performed: a request will be sent to all nodes and the consecutive communication
           continues with the node, which will be the first to reply.

       The "Authen::Radius" module provides a simple class that allows you to send/receive Radius
       requests/responses to/from a Radius server.

       load_dictionary ( [ DICTIONARY ], [format => 'freeradius' | 'gnuradius'] )
           Loads the definitions in the specified Radius dictionary file (standard Livingston  radiusd  format).
           Tries  to  load  "/etc/raddb/dictionary"  when  no argument is specified, or dies. "format" should be
           specified if dictionary has other format (currently supported: FreeRADIUS and GNU Radius)

           NOTE: you need to load valid dictionary if you plan to send RADIUS  requests  with  attributes  other
           than just "User-Name"/"Password".

       check_pwd ( USERNAME, PASSWORD [,NASIPADDRESS] )
           Checks  with  the  RADIUS  server  if  the  specified "PASSWORD" is valid for user "USERNAME". Unless
           "NASIPADDRESS" is specified, the script will attempt to determine it's local IP address  (IP  address
           for the RADIUS socket) and this value will be placed in the NAS-IP-Address attribute.  This method is
           actually  a  wrapper  for subsequent calls to "clear_attributes", "add_attributes", "send_packet" and
           "recv_packet". It returns 1 if the "PASSWORD" is correct, or undef otherwise.

       add_attributes ( { Name => NAME, Value => VALUE [, Type => TYPE] [, Vendor => VENDOR] [, Tag => TAG ] },
       ... )
           Adds any number of Radius attributes to the current Radius object. Attributes are specified as a list
           of anon hashes. They may be "Name"d with their dictionary name (provided a dictionary has been loaded
           first), or with their raw Radius attribute-type values. The "Type"  pair  should  be  specified  when
           adding  attributes  that  are  not  in  the dictionary (or when no dictionary was loaded). Values for
           "TYPE"  can  be  '"string"',  '"integer"',  '"ipaddr"',  '"ipv6addr"',  '"ipv6prefix"',  '"ifid"'  or
           '"avpair"'.  The  "VENDOR"  may  be Vendor's name from the dictionary or their integer id. For tagged
           attributes (RFC2868) tag can be specified in "Name" using 'Name:Tag' format, or by using "Tag"  pair.
           TAG value is expected to be an integer, within [1:31] range (zero value isn't supported).

       get_attributes
           Returns a list of references to anon hashes with the following key/value pairs : { Name => NAME, Code
           =>  RAWTYPE,  Value => VALUE, RawValue => RAWVALUE, Vendor => VENDOR, Tag => TAG, AttrName => NAME }.
           Each hash represents an attribute in the current object. The "Name" and "Value"  pairs  will  contain
           values  as  translated  by the dictionary (if one was loaded). The "Code" and "RawValue" pairs always
           contain the raw attribute type & value as received from the server.  If some attribute doesn't  exist
           in  dictionary or type of attribute not specified then corresponding "Value" undefined and "Name" set
           to attribute ID ("Code" value). For tagged attribute (RFC2868), it will  include  the  tag  into  the
           "NAME"  as  'Name:Tag'.  Original Name is stored in "AttrName".  Also value of tag is stored in "Tag"
           (undef for non-tagged attributes).

       clear_attributes
           Clears all attributes for the current object.

       send_packet ( REQUEST_TYPE, RETRANSMIT )
           Packs up a Radius packet based on the current secret & attributes and sends it to the server  with  a
           Request   type   of   "REQUEST_TYPE".   Exported   "REQUEST_TYPE"   methods   are   "ACCESS_REQUEST",
           "ACCESS_ACCEPT", "ACCESS_REJECT",  "ACCESS_CHALLENGE",  "ACCOUNTING_REQUEST",  "ACCOUNTING_RESPONSE",
           "ACCOUNTING_STATUS", "STATUS_SERVER", "DISCONNECT_REQUEST", "DISCONNECT_ACCEPT", "DISCONNECT_REJECT",
           "COA_REQUEST",  "COA_ACCEPT",  "COA_REJECT",  "COA_ACK",  and "COA_NAK".  Returns the number of bytes
           sent, or undef on failure.

           If the RETRANSMIT parameter is provided and contains a non-zero value, then it is considered that  we
           are  re-sending  the  request,  which was already sent previously. In this case the previous value of
           packet identifier is used.

       recv_packet ( DETECT_BAD_ID )
           Receives a Radius reply packet. Returns the Radius Reply type (see possible values for "REQUEST_TYPE"
           in method "send_packet") or undef on failure. Note that failure may be due to a failed  recv()  or  a
           bad Radius response authenticator. Use "get_error" to find out.

           If  the  DETECT_BAD_ID  parameter  is supplied and contains a non-zero value, then calculation of the
           packet identifier is performed before authenticator check and EBADID  error  returned  in  case  when
           packet  identifier  from  the  response  doesn't  match  to  the request. If the DETECT_BAD_ID is not
           provided or contains zero value then EBADAUTH returned in such case.

       set_timeout ( TIMEOUT )
           Sets socket I/O activity timeout. "TIMEOUT" should be specified in floating seconds since the epoch.

       get_error
           Returns the last "ERRORCODE" for the current object. Errorcodes are one-word strings always beginning
           with an '"E"'.

       strerror ( [ ERRORCODE ] )
           Returns a verbose error string for the last error for  the  current  object,  or  for  the  specified
           "ERRORCODE".

       error_comment
           Returns  the  last error explanation for the current object. Error explanation is generated by system
           call.

       get_active_node
           Returns currently active radius node in standard numbers-and-dots notation  with  port  delimited  by
           colon.

       Authen::Radius - provide simple Radius client facilities

         use Authen::Radius;

         $r = new Authen::Radius(Host => 'myserver', Secret => 'mysecret');
         print "auth result=", $r->check_pwd('myname', 'mypwd'), "\n";

         $r = new Authen::Radius(Host => 'myserver', Secret => 'mysecret');
         Authen::Radius->load_dictionary();
         $r->add_attributes (
               { Name => 'User-Name', Value => 'myname' },
               { Name => 'Password', Value => 'mypwd' },
       # RFC 2865 http://www.ietf.org/rfc/rfc2865.txt calls this attribute
       # User-Password. Check your local RADIUS dictionary to find
       # out which name is used on your system
       #       { Name => 'User-Password', Value => 'mypwd' },
               { Name => 'h323-return-code', Value => '0' }, # Cisco AV pair
               { Name => 'Digest-Attributes', Value => { Method => 'REGISTER' } }
         );
         $r->send_packet(ACCESS_REQUEST) and $type = $r->recv_packet();
         print "server response type = $type\n";
         for $a ($r->get_attributes()) {
           print "attr: name=$a->{'Name'} value=$a->{'Value'}\n";
         }