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


  my $auth = Net::SIP::Authorize->new(
        dispatcher => $dispatcher,
        realm      => '',
        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 ]


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.


new ( %ARGS )

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


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


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


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


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.


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.


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.


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:


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


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


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


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


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.