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.

perl v5.36.0                                       2023-09-29                           Net::SIP::Authorize(3pm)