.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Radius::Packet 3pm" .TH Radius::Packet 3pm "2015-05-05" "perl v5.20.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Net::Radius::Packet \- Object\-oriented Perl interface to RADIUS packets .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& 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(\*(AqUser\-Name\*(Aq eq "lwall") { \& my $resp = new Net::Radius::Packet $d; \& $resp\->set_code(\*(AqAccess\-Accept\*(Aq); \& $resp\->set_identifier($p\->identifier); \& $resp\->set_authenticator($p\->authenticator); \& $resp\->set_attr(\*(AqReply\-Message\*(Aq => "Welcome, Larry!\er\en"); \& my $respdat = auth_resp($resp\->pack, "mysecret"); \& ... \& \& die "Packet is a fake response\en" if ($p\->code eq \*(AqAccess\-Accept\*(Aq \& and not auth_req_verify($data, $secret, $req\->authenticator)) \& \& die "Packet is a fake\en" if ($p\->code eq \*(AqAccounting\-Request\*(Aq \& and not auth_acct_verify($data, $secret)) .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\s-1RADIUS \s0(\s-1RFC2138\s0) specifies a binary packet format which contains various values and attributes. Net::Radius::Packet provides an interface to turn \s-1RADIUS\s0 packets into Perl data structures and vice-versa. .PP Net::Radius::Packet does not provide functions for obtaining \s-1RADIUS\s0 packets from the network. A simple network \s-1RADIUS\s0 server is provided as an example at the end of this document. .SS "\s-1PACKAGE METHODS\s0" .IX Subsection "PACKAGE METHODS" .ie n .IP "\fBnew Net::Radius::Packet \fB$dictionary\fB, \f(BI$data\fB\fR" 4 .el .IP "\fBnew Net::Radius::Packet \f(CB$dictionary\fB, \f(CB$data\fB\fR" 4 .IX Item "new Net::Radius::Packet $dictionary, $data" Returns a new Net::Radius::Packet object. \f(CW$dictionary\fR is an optional reference to a Net::Radius::Dictionary object. If not supplied, you must call \fBset_dict\fR. .Sp If \f(CW$data\fR is supplied, \fBunpack\fR will be called for you to initialize the object. .SS "Proxy-State, \s-1RFC\s0 specification" .IX Subsection "Proxy-State, RFC specification" From \s-1RFC\-2865:\s0 .PP .Vb 1 \& 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. .Ve .SS "Proxy-State, Implementation" .IX Subsection "Proxy-State, Implementation" \&\f(CW\*(C`\->pack()\*(C'\fR and \f(CW\*(C`\->dump()\*(C'\fR 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. .PP \&\f(CW\*(C`\->attr()\*(C'\fR method always return the last attribute inserted. .PP \&\f(CW\*(C`\->set_attr()\*(C'\fR and \f(CW\*(C`\->set_vsattr()\*(C'\fR 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 \f(CW\*(C`\->unset_attr()\*(C'\fR and \f(CW\*(C`\->unset_vsattr()\*(C'\fR perform the opposite function. .SS "\s-1OBJECT METHODS\s0" .IX Subsection "OBJECT METHODS" There are actually two families of object methods. The ones described below deal with standard \s-1RADIUS\s0 attributes. An additional set of methods handle the Vendor-Specific attributes as defined in the \s-1RADIUS\s0 protocol. Those methods behave in much the same way as the ones below with the exception that the prefix \fBvs\fR must be applied before the \fBattr\fR in most of the names. The vendor code must also be included as the first parameter of the call. .PP The \fBvsattr\fR and \fBset_vsattr\fR 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. .IP "\fB\->set_dict($dictionary)\fR" 4 .IX Item "->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 \->\fBpack\fR or \->\fBunpack\fR. .IP "\fB\->unpack($data)\fR" 4 .IX Item "->unpack($data)" Given a raw \s-1RADIUS\s0 packet \f(CW$data\fR, unpacks its contents so that they can be retrieved with the other methods (\fBcode\fR, \fBattr\fR, etc.). .IP "\fB\->pack\fR" 4 .IX Item "->pack" Returns a raw \s-1RADIUS\s0 packet suitable for sending to a \s-1RADIUS\s0 client or server. .IP "\fB\->code\fR" 4 .IX Item "->code" Returns the Code field as a string. As of this writing, the following codes are defined: .Sp .Vb 10 \& 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 .Ve .IP "\fB\->set_code($code)\fR" 4 .IX Item "->set_code($code)" Sets the Code field to the string supplied. .IP "\fB\->\f(BIidentifier()\fB\fR" 4 .IX Item "->identifier()" Returns the one-byte Identifier used to match requests with responses, as a character value. .IP "\fB\->set_identifier($id)\fR" 4 .IX Item "->set_identifier($id)" Sets the Identifier byte to the character supplied. .IP "\fB\->\f(BIauthenticator()\fB\fR" 4 .IX Item "->authenticator()" Returns the 16\-byte Authenticator field as a character string. .IP "\fB\->set_authenticator($authenticator)\fR" 4 .IX Item "->set_authenticator($authenticator)" Sets the Authenticator field to the character string supplied. .IP "\fB\->attr($name)\fR" 4 .IX Item "->attr($name)" Retrieves the value of the named Attribute. Attributes will be converted automatically based on their dictionary type: .Sp .Vb 4 \& 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 .Ve .Sp The following types are simply mapped to other types until correct encoding is implemented: .RS 4 .IP "\fBipv6addr\fR" 4 .IX Item "ipv6addr" Treated as a string .IP "\fBdate\fR" 4 .IX Item "date" Treated as a string .IP "\fBifid\fR" 4 .IX Item "ifid" Treated as a string .RE .RS 4 .Sp When multiple attributes are inserted in the packet, the last one is returned. .RE .ie n .IP "\fB\->set_attr($name, \fB$val\fB, \f(BI$rewrite_flag\fB)\fR" 4 .el .IP "\fB\->set_attr($name, \f(CB$val\fB, \f(CB$rewrite_flag\fB)\fR" 4 .IX Item "->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 \fBattr\fR 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. .ie n .IP "\fB\->set_vsattr($vendor, \fB$name\fB, \f(BI$val\fB, \f(CB$rewrite_flag\fB)\fR" 4 .el .IP "\fB\->set_vsattr($vendor, \f(CB$name\fB, \f(CB$val\fB, \f(CB$rewrite_flag\fB)\fR" 4 .IX Item "->set_vsattr($vendor, $name, $val, $rewrite_flag)" Analogous to \f(CW\*(C`\->set_attr()\*(C'\fR, but operates on vendor-specific attributes for vendor \f(CW$vendor\fR. .IP "\fB\->unset_attr($name)\fR" 4 .IX Item "->unset_attr($name)" Sets the named Attribute to the given value. Values should be supplied as they would be returned from the \fBattr\fR method. .ie n .IP "\fB\->unset_vsattr($vendor, \fB$name\fB)\fR" 4 .el .IP "\fB\->unset_vsattr($vendor, \f(CB$name\fB)\fR" 4 .IX Item "->unset_vsattr($vendor, $name)" Analogous to \f(CW\*(C`\->unset_attr()\*(C'\fR, but operates on vendor-specific attributes for vendor \f(CW$vendor\fR. .IP "\fB\->attr_slot($integer)\fR" 4 .IX Item "->attr_slot($integer)" Deprecated synonym for \f(CW\*(C`\->attr_slot_val()\*(C'\fR. .IP "\fB\->\f(BIattr_slots()\fB\fR" 4 .IX Item "->attr_slots()" Return the number of attribute slots in the packet. .IP "\fB\->attr_slot_name($integer)\fR" 4 .IX Item "->attr_slot_name($integer)" Retrieves the attribute name of the given slot number from the Attributes stack. Returns undef when the slot is vacant. .IP "\fB\->attr_slot_val($integer)\fR" 4 .IX Item "->attr_slot_val($integer)" Retrieves the attribute value of the given slot number from the Attributes stack. Returns undef when the slot is vacant. .IP "\fB\->\f(BIunset_attr_slot\fB($integer)\fR" 4 .IX Item "->unset_attr_slot($integer)" Removes given stack position from the Attributes stack. .IP "\fB\->password($secret, [$attr])\fR" 4 .IX Item "->password($secret, [$attr])" The \s-1RADIUS\s0 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 \s-1RADIUS\s0 attribute, by using the second argument. .ie n .IP "\fB\->set_password($passwd, \fB$secret\fB, [$attribute])\fR" 4 .el .IP "\fB\->set_password($passwd, \f(CB$secret\fB, [$attribute])\fR" 4 .IX Item "->set_password($passwd, $secret, [$attribute])" The \s-1RADIUS\s0 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 \f(CW$attribute\fR, which defaults to \&'User\-Password'. .Sp 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. .IP "\fB\->\f(BIdump()\fB\fR" 4 .IX Item "->dump()" Prints the content of the packet to \s-1STDOUT.\s0 .IP "\fB\->show_unknown_entries($bool)\fR" 4 .IX Item "->show_unknown_entries($bool)" Controls the generation of a \f(CW\*(C`warn()\*(C'\fR whenever an unknown tuple is seen. .SS "\s-1EXPORTED SUBROUTINES\s0" .IX Subsection "EXPORTED SUBROUTINES" .ie n .IP "\fBauth_resp($packed_packet, \fB$secret\fB [, accounting])\fR" 4 .el .IP "\fBauth_resp($packed_packet, \f(CB$secret\fB [, accounting])\fR" 4 .IX Item "auth_resp($packed_packet, $secret [, accounting])" Given a (packed) \s-1RADIUS\s0 packet and a shared secret, returns a new packet with the Authenticator field changed in accordace with \s-1RADIUS\s0 protocol requirements. .Sp 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. .ie n .IP "\fBauth_acct_verify($packet, \fB$secret\fB)\fR" 4 .el .IP "\fBauth_acct_verify($packet, \f(CB$secret\fB)\fR" 4 .IX Item "auth_acct_verify($packet, $secret)" Verifies the authenticator in an \fBAccounting-Request\fR packet as explained in \s-1RFC\-2866.\s0 Returns 1 if the authenticator matches the packet and the secret, undef otherwise. .Sp \&\f(CW$packet\fR is the packet data, as received. \f(CW$secret\fR is the corresponding shared secret. .ie n .IP "\fBauth_req_verify($packet, \fB$secret\fB, \f(BI$prev_auth\fB)\fR" 4 .el .IP "\fBauth_req_verify($packet, \f(CB$secret\fB, \f(CB$prev_auth\fB)\fR" 4 .IX Item "auth_req_verify($packet, $secret, $prev_auth)" Verifies the authenticator in \fBAccess-Accept\fR, \fBAccess-Reject\fR, and \&\fBAccess-Challenge\fR packets as explained in \s-1RFC\-2865.\s0 Returns 1 if the authenticator matches the packet and the secret, undef otherwise. .Sp \&\f(CW$packet\fR is the packet data, as received. \f(CW$secret\fR is the corresponding shared secret. \f(CW$prev_auth\fR is the authenticator taken from the corresponding \fBAccess-Accept\fR packet. .Sp It's the application's job to keep track of the authenticators in each request. .SH "EXAMPLE" .IX Header "EXAMPLE" See the examples included in the \fBexamples/\fR directory of the distribution. Also see \fINet::Radius::Server\fR\|(3) for a more complete implementation of a \s-1RADIUS\s0 server. .SH "AUTHOR" .IX Header "AUTHOR" Christopher Masto, . \s-1VSA\s0 support by Luis E. Mun\*~oz, . Fix for unpacking 3COM VSAs contributed by Ian Smith . Information for packing of 3Com VSAs provided by Quan Choi . Some functions contributed by Tony Mountifield . Attribute ordering provided by Toni Prug, , idea by Bill Hulley. .SH "SEE ALSO" .IX Header "SEE ALSO" Perl, \fINet::Radius::Server\fR\|(3), \fINet::Radius::Dictionary\fR\|(3), RFCs 2865, 2866, 2882 and 3575.