-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1



Net::Radius Modules
===================

The modules included here provide an interface to the RADIUS
protocol. It consists of the following modules:

Net::Radius::Packet	- Deals with RADIUS packets
Net::Radius::Dictionary	- Deals with RADIUS dictionaries

This module is essentially the original RADIUS-1.0 distribution by
Christopher Masto plus a number of changes and fixes by Luis Muñoz and
Ian Smith.

It has been changed so that it better fits the CPAN namespace. See the
other README.* files in this archive for additional information.

The installation follows the standard protocol...

$ perl Makefile.PL
$ make
$ make test
$ make install

The ./examples directory contain a number of simple examples.

This code supports the use of vendor specific attributes. This
type of attribute is defined in RFC-2138 and is used to support
'propietary' extensions on top of the base RADIUS specification.

There are two new kinds of entries in the RADIUS dictionary in
order to specify VSAs.

VENDORATTR <vendor> <attribute> <id> <type>

This entry is used to create a new kind of vendor attribute,
such as in this example

VENDORATTR 	9 	cisco-avpair 	1 	string

This creates a new vendor-specific attribute for vendor 9 (Cisco
Systems), with name 'cisco-avpair'. This attribute is identified by
numeric id '1' and is associated with a string value.

The second type of entry allows the specification of named values.
The following is an hypotetical example of named value entry.

VENDORATTR	9	cisco-enum	254	integer
VENDORVALUE	9	cisco-enum	Value-1	1
VENDORVALUE	9	cisco-enum	Value-2	2
VENDORVALUE	9	cisco-enum	Value-3	3

Alternatively, you can use the widely deployed FreeRadius dictionary
files' syntax of:

VENDOR		Cisco		9
ATTRIBUTE	Cisco-AVPair	1	string		Cisco

About the stability, this code has been in very active use at a
largish ISP with millions of users using a variety of network
equipment with impressive results. It has been succesfully used under
FreeBSD, Linux, Solaris and Tru64.

There's copious support material along with this distribution. Please
do take a look.

DO YOU WANT TO THANK ME?

If  you consider this  a valuable  contribution, there  is a  web page
where you can express your gratitude. Please see

	http://mipagina.cantv.net/lem/thanks-en.html (English)
	http://mipagina.cantv.net/lem/thanks-es.html (Spanish)

SECURITY CONSIDERATIONS

I have no control on the machanisms involved in the storage or
transport of this distribution. This means that I cannot guarantee
that the distribution you have in your hands is indeed, the same
distribution I packed and uploaded.

Along the distribution file, you should have a file with the extension
".asc". This contains a GPG "detached signature" that makes it
impossible for anybody to alter this distribution. If security is of
any concern to you, by all means verify the signature of this file and
contact the author if any discrepancy is detected.

You can find more information about this at the following URL

             http://mipagina.cantv.net/lem/gpg/

COPYRIGHT AND LICENSE

Original work (c) Christopher Masto. Changes (c) 2002,2003 Luis
E. Muñoz <luismunoz@cpan.org>.

This software can be used under the same terms as perl itself. It also
carries the same warranties.

Please send bug reports (or patches) as well as feedback and
suggestions to

luismunoz@cpan.org

When submitting bugs, it is very important that you include the
relevant information for reproducing the bug. Packet dumps are most
useful.

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.1 (Darwin)

iD8DBQFEznquQyDWGRI/hhARAq37AJ4nwkdiU1eqgpTObZ0G2QZ0jvQU2QCgkR28
nf3syw7TJsGGyrr/KSTcyfU=
=Of85
-----END PGP SIGNATURE-----

Feb 21 2001:

Finally the VSA packing/unpacking works with 3Com equipment. Ian Smith
contributed  code to  unpack  VSAs  coming from  the  3Com. Quan  Choi
reported   useful   information   regarding   the  encoding   of   the
VSAs.  According  to  Quan,  3Com  packs the  VSAs  according  to  the
following structure:

   0                   1                   2                   3
   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |     Type      |  Length       |            Vendor-Id
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
        Vendor-Id (cont)           |      Sub-Attribute Type
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
          Sub-Attribute Type       |        Payload...             |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Which is fine,  as RFC-2138 does not mandate  any particular structure
for the Vendor-Specific payload.

Thanks to both Ian and Quan for the help.

luismunoz@cpan.org

$Id: README.3COM 7 2003-01-08 03:42:41Z lem $

Vendor-Specific Attribute support

This code supports the use of vendor specific attributes. This
type of attribute is defined in RFC-2138 and is used to support
'propietary' extensions on top of the base RADIUS specification.

There are two new kinds of entries in the RADIUS dictionary in
order to specify VSAs.

VENDORATTR <vendor> <attribute> <id> <type>

This entry is used to create a new kind of vendor attribute,
such as in this example

VENDORATTR 	9 	cisco-avpair 	1 	string

This creates a new vendor-specific attribute for vendor 9 (Cisco
Systems), with name 'cisco-avpair'. This attribute is identified by
numeric id '1' and is associated with a string value.

The second type of entry allows the specification of named values.
The following is an hypotetical example of named value entry.

VENDORATTR	9	cisco-enum	254	integer
VENDORVALUE	9	cisco-enum	Value-1	1
VENDORVALUE	9	cisco-enum	Value-2	2
VENDORVALUE	9	cisco-enum	Value-3	3

Questions and comments about the package can be sent to the
author of the module, Christopher Masto <chris@netmonger.net>.

Questions and comments about the VSA support can be directed
to the author of this part of the code, Luis E. Mu�oz
<luismunoz@cpan.org>

Ian Smith <iansmith@ncinter.net> contributed code for 3COM
VSAs.

$Id: README.VSA 7 2003-01-08 03:42:41Z lem $

* NAS-IP-Address and other "ipaddr" encoding inconsistencies

  I've confirmed some reports that the Alcatel 5620 SAM Release 3.0
  and possibly other endpoints from this or other vendors, are
  improperly encoding the IP address in the NAS-IP-Address tuple. The
  relevant RFCs state that NAS-IP-Address should be encoded as four
  octets, MSB. However, this device seems to be packing the argument
  as a plain string.

  This error may manifest itself as a parameter length mismatch with
  inet_ntoa() in earlier versions of Net::Radius. A packet dump
  exhibiting this problem looks like this...

  $ tcpdump -vvv -nr tcpdump-radius.out
  reading from file tcpdump-radius.out, link-type EN10MB (Ethernet)
  16:13:29.540605 IP (tos 0x0, ttl 250, id 41011, offset 0, flags
  [DF], length: 108) 10.120.156.15.33452 > 161.196.109.5.1645: RADIUS,
  length: 80
        Access Request (1), id: 0x78, Authenticator: ...
          NAS IP Address Attribute (4), length: 15, Value: ERROR: length 13 != 4
            0x0000:  3130 2e31 3230 2e31 3536 2e31 35

  Note the error pointed out by tcpdump, referring to the length of
  the attribute.

  In order to improve interoperability, I've included code that allows
  decoding of these packets, by simply returning the enclosed string
  "as is" to the calling script.

On Debian systems, all the bundled dictionaries are placed in
/usr/share/libnet-radius-perl/dicts.

Documentation is placed in /usr/share/doc/libnet-radius-perl/ as per
the Debian Policy.

For other distributions or under manual installation, you may need to
locate those files manually according to your needs.

Luis E. Muñoz / 2009-08-25

As of version 1.52, Net::Radius includes the "packet tests". Those
packet tests consist of RADIUS packets captured in various production
environments and passed through Net::Radius, to see how it fares with
real-world data.

Ideally, every bug report about Net::Radius related to the dialog with
a given network device, should include a proper packet capture that
allows for the reproduction of the problem. This also allows the
implementation of regression tests that will insure that packets will
be decoded properly in later versions of this distribution.

To be useful, a packet capture must include the complete (binary) RADIUS
packet(s) in one or more files. Also, the following information would
be of help:

* RADIUS Secret and Auhenticator, if applicable and known

* Name, version and relevant information about the device producing
  the packet

* Relevant dictionary entries to properly decode the packet
  attributes. This is specially important with Vendor-Specific
  Attributes

* If you're including more than a single packet, please specify what
  each one should contain

If the packet dump is being provided as part of a bug report, a
concise explanation about why the Net::Radius handling of the packet
is incorrect and what the correct or expected result is. If you have
references to document this further, please provide them as
well. Packet dumps from other RADIUS server doing "the right thing"
are worth extra points.

If you want to contribute with the production of more packet tests,
please consider the following:

* Devices not currently included in the packet tests are
  welcome. Exotic, old or obsoleted devices are even more welcome (Any
  PortMaster 2 or 3 out there?)

* Ideally, try to provide at least one sample packet of each type that
  your device is able to send (ie, Access-Request, Accounting-Request,
  etc)

* Packet dumps will be copied straight into the distribution - You're
  responsible for safeguarding any private or restricted information
  on the packets, such as the RADIUS secret, user names or passwords,
  IP addresses, etc.

HOW TO PRODUCE A PACKET DUMP

Packet dumps can be produced with any tool whose output is supported
by wireshark (formerly, ethereal), which is then used to extract the
packet payload and build the corresponding test. My recommendation is
to use the tcpdump utility, available in many operating systems. There
are other compatible utilities that can store captured packets as raw
binary files, which can be compressed and sent via email or attached
to a bug report.

By way of example, let's say that the RADIUS server is located at IP
address 10.0.0.1, serving requests in the UDP ports 1812 and 1813 for
authentication and accounting respectively, while the device whose
dialog we want to capture, uses IP address 10.0.0.5. Packets from the
device to the server could be captured using the following command (in
a single line):

tcpdump -s 0 -c 1 -w radius.dump -e 'src host 10.0.0.5 and dst host
  10.0.0.1 and udp and portrange 1812-1813'

Of course, the machine must have an interface connected so that
traffic can be sniffed, whose name may have to be specified. Note that
only one packet is being captured (-c option) although you could
capture more that this.

Likewise, response packets from the RADIUS server to the device can be
captured with the following command:

tcpdump -s 0 -c 1 -w radius.dump -e 'src host 10.0.0.1 and dst host
  10.0.0.5 and udp and portrange 1812-1813'

tcpdump has a nice and extensive manual page that explains all of its
options. Please take a look at it so that you understand independently
what the incantations I've provided above actually do or conversely,
whether there is something else you may need to do in your environment
to acurately record the information you want.

IMPORTANT: Remember that full packets are needed for proper
testing. Make sure your captures include all of the packet
payload. Including only the packet headers make for a very poor test
input. In the examples above, the -s option takes care of this.

The commands disussed above will capure packets to/from the relevant
devices, leavig them in the file radius.dump that you can now
send. Remember to record and include the useful information mentioned
in the first part of these instructions.

If you want to provide the source file for the tests directly, please
take a look at the file packets/README

This distribution includes a few RADIUS servers with different degrees
if functionality in the examples directory. If you're considering
writing a RADIUS server, take a look at Net::Radius::Server before
starting.

Net::Radius::Server is an extensible framework allowing the creation
of RADIUS servers with very little programming. Complex tasks are
easily accomplished by means of a pipeline architecture in which each
request is matched and then acted upon by Perl code.

Classes implementing common tasks are already included.