---
name: "Net::SIP::Authorize"
section: "3pm"
platform: "linux"
package: "libnet-sip-perl"
version: "0.838-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Net::SIP::Authorize"
---

# Net::SIP::Authorize(3pm)

enforce authorization of packets

## 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.