=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 user2pass

Either hash reference with C<user,password> mapping or callback,
which gives C<password> if called with 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>.

=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