=head1 NAME
Net::SIP::Authorize - enforce authorization of packets
=head1 SYNOPSIS
my $auth = Net::SIP::Authorize->new(
dispatcher => $dispatcher,
realm => 'net-sip.example.com',
user2pass => \&give_pass_for_user,
i_am_proxy => 1,
);
my $proxy = Net::SIP::StatelessProxy->new...
my $chain = Net::SIP::ReceiveChain->new(
# all requests for proxy need to be authorized
[ $auth,$proxy ]
);
=head1 DESCRIPTION
This package is used inside a L<Net::SIP::ReceiveChain> to make sure,
that requests are authorized before they get handled by the next
receiver in the chain.
=head1 CONSTRUCTOR
=over 4
=item new ( %ARGS )
This creates a new registar object, %ARGS can have the following keys:
=over 8
=item dispatcher
L<Net::SIP::Dispatcher> object manging the registar. Mandatory.
=item realm
The realm for the authentication request. Defaults to 'p5-net-sip'.
=item opaque
Optional value for C<opaque> parameter for the authentication request.
If none is given no C<opaque> parameter will be used.
=item user2a1
Either hash reference with C<user,a1_hex> mapping or callback, which gives
C<a1_hex> if called with C<user,realm>.
For the meaning of C<a1_hex> see RFC 2617.
=item user2pass
Either hash reference with C<user,password> mapping or callback,
which gives C<password> if called with C<user>.
This parameter will only be used if C<user2a1> does not result in
a defined C<a1_hex> for C<user>.
=item i_am_proxy
Flag if the object behind works as a proxy (e.g. L<Net::SIP::StatelessProxy>)
and sends C<Proxy-Authenticate> or if it is an endpoint
(e.g. L<Net::SIP::Endpoint>, L<Net::SIP::Registrar>) which sends
C<WWW-Authenticate>.
=item filter
Additional filter for authorization, e.g. if authorization based on
username and passwort succeeded it might still fail because of these
filters. Filter is a hash with the method as key.
The value can be an additional authorization (in which case it
must succeed), a list of authorizations (all of them must succeed),
or a list with a list of authorizations (at least one of the inner
lists must succeed).
The additional authorization can be a name of a L<Net::SIP::Authorize>
subclass (e.g. C<ToIsFrom> means C<Net::SIP::Authorize::ToIsFrom>)
which has a C<verify> function or a C<[\&callback]>.
The verify function or callback will be called with
C<($packet,$leg,$addr,$auth_user,$auth_realm)> where C<$packet> is
the request, C<$leg> the L<Net::SIP::Leg> object where the packet
came in, C<$addr> the senders address, C<$auth_user> the
username from the authorized user and C<$auth_realm> the realm
which was used for authorization.
Success for verification means that the function must return true.
The following authorization subclasses are defined:
=over 4
=item FromIsRealm
Succeeds if the senders domain is the realm or a subdomain of the realm.
=item FromIsAuthUser
Succeeds if the username of the sender equals the username used for
authorization.
=item ToIsFrom
Succeeds if To header equals From header. This can be used to make sure, that a
user can only call REGISTER for itself.
=back
Example:
filter => {
REGISTER => [
# all of these must succeed
[ 'ToIsFrom','FromIsRealm','FromIsAuthUser' ],
# or this
[ \&callback ],
],
INVITE => 'FromIsRealm',
}
=back
=back
=head1 METHODS
=over 4
=item receive ( PACKET,LEG,FROM )
PACKET is the incoming packet,
LEG is the L<Net::SIP::Leg> where the packet arrived and FROM
is the C<< "ip:port" >> of the sender. Responses will be send
back to the sender through the same leg.
Called from the managing L<Net::SIP::Dispatcher> object if a new
packet arrives.
Returns TRUE if the packet was fully handled by this object which
is the case, if the packet was not authorized so that a C<401>
or C<407> (if C<i_am_proxy>) response was send back.
Returns FALSE if packet was authorized and should be handled
be the next object in the L<Net::SIP::ReceiveChain>.
In this case it usually changes the packet to remove the local
authorization information.
=back