NAME

       Net::SIP::Authorize - enforce authorization of packets

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 ]
         );

DESCRIPTION

       This package is used inside a Net::SIP::ReceiveChain to make sure, that requests are
       authorized before they get handled by the next receiver in the chain.

CONSTRUCTOR

       new ( %ARGS )
           This creates a new registar object, %ARGS can have the following keys:

           dispatcher
                   Net::SIP::Dispatcher object manging the registar. Mandatory.

           realm   The realm for the authentication request. Defaults to 'p5-net-sip'.

           opaque  Optional value for "opaque" parameter for the authentication request.  If none
                   is given no "opaque" parameter will be used.

           user2a1 Either hash reference with "user,a1_hex" mapping or callback, which gives
                   "a1_hex" if called with "user,realm".  For the meaning of "a1_hex" see RFC
                   2617.

           user2pass
                   Either hash reference with "user,password" mapping or callback, which gives
                   "password" if called with "user".  This parameter will only be used if
                   "user2a1" does not result in a defined "a1_hex" for "user".

           i_am_proxy
                   Flag if the object behind works as a proxy (e.g. Net::SIP::StatelessProxy) and
                   sends "Proxy-Authenticate" or if it is an endpoint (e.g. Net::SIP::Endpoint,
                   Net::SIP::Registrar) which sends "WWW-Authenticate".

           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 Net::SIP::Authorize subclass
                   (e.g. "ToIsFrom" means "Net::SIP::Authorize::ToIsFrom") which has a "verify"
                   function or a "[\&callback]".

                   The verify function or callback will be called with
                   "($packet,$leg,$addr,$auth_user,$auth_realm)" where $packet is the request,
                   $leg the Net::SIP::Leg object where the packet came in, $addr the senders
                   address, $auth_user the username from the authorized user and $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:

                   FromIsRealm
                       Succeeds if the senders domain is the realm or a subdomain of the realm.

                   FromIsAuthUser
                       Succeeds if the username of the sender equals the username used for
                       authorization.

                   ToIsFrom
                       Succeeds if To header equals From header. This can be used to make sure,
                       that a user can only call REGISTER for itself.

                   Example:

                     filter => {
                       REGISTER => [
                         # all of these must succeed
                         [ 'ToIsFrom','FromIsRealm','FromIsAuthUser' ],
                         # or this
                         [ \&callback ],
                       ],
                       INVITE => 'FromIsRealm',
                     }

METHODS

       receive ( PACKET,LEG,FROM )
           PACKET is the incoming packet, LEG is the Net::SIP::Leg where the packet arrived and
           FROM is the "ip:port" of the sender. Responses will be send back to the sender through
           the same leg.

           Called from the managing 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 401 or 407 (if "i_am_proxy") response was send
           back.

           Returns FALSE if packet was authorized and should be handled be the next object in the
           Net::SIP::ReceiveChain.  In this case it usually changes the packet to remove the
           local authorization information.