Net::S...thorize(3pm)

👑 Net::SIP::Authorize — the vibe check for your packets 💅

okay bestie, gather round, because this little Perl module from the User Contributed Perl Documentation corner of the internet is literally the bouncer at the door of your SIP party 🎀

✨ NAME ✨

Net::SIP::Authorize — it enforces authorization of packets. that's it, that's the job. no packet gets past without showing ID. periodt.

---

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

see how $auth sits right in front of $proxy in the chain? yeah. it's giving bodyguard. it's giving "you shall not pass". 🫶

---

💖 DESCRIPTION 💖

so basically this package lives inside a Net::SIP::ReceiveChain, and its whole personality is making sure requests are authorized before they get handed off to the next receiver in the chain. no authorized? no entry. next receiver doesn't even get to look at it. 🔥

---

🦋 CONSTRUCTOR 🦋

new ( %ARGS )

this spins up a brand new object, and %ARGS can carry any of these keys, bestie:

• dispatcher — a Net::SIP::Dispatcher object managing the registar. Mandatory, like you cannot skip this one, it's not optional, it's the whole point. 😭
• realm — the realm for the authentication request. defaults to 'p5-net-sip' if you don't say anything. 💜
• opaque — optional value for the "opaque" parameter on the authentication request. if you don't give one, no "opaque" parameter gets used at all. simple as that. ✨
• user2a1 — either a hash reference with a "user,a1_hex" mapping, or a callback that gives you "a1_hex" when it's called with "user,realm". for what "a1_hex" even means, go read RFC 2617, iykyk. 📚
• user2pass — either a hash reference with a "user,password" mapping, or a callback that gives you "password" when called with "user". heads up though: this one only gets used if "user2a1" does not result in a defined "a1_hex" for "user". it's the backup plan, the understudy, the second choice. 🙈
• i_am_proxy — a flag for whether the object behind this works as a proxy (think Net::SIP::StatelessProxy) and sends "Proxy-Authenticate", or whether it's an endpoint (think Net::SIP::Endpoint, Net::SIP::Registrar) which sends "WWW-Authenticate". pick your fighter. 👑
• filter — extra filter for authorization. like, even if the username + password authorization succeeded, it might still fail because of these filters. the filter is a hash with the method as the 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).

that additional authorization can be the name of a Net::SIP::Authorize subclass (so like, "ToIsFrom" means "Net::SIP::Authorize::ToIsFrom") which has a "verify" function, or it can be a "[\&callback]".

the verify function or callback gets called with "($packet,$leg,$addr,$auth_user,$auth_realm)" where $packet is the request, $leg is the Net::SIP::Leg object where the packet came in, $addr is the sender's address, $auth_user is the username from the authorized user, and $auth_realm is the realm that was used for authorization. success for verification means the function must return true. no true, no pass. 🚫

the following authorization subclasses are defined:

• FromIsRealm — succeeds if the sender's 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 the To header equals the From header. this one is perfect for making sure a user can only call REGISTER for itself. main character boundaries, honestly. 🎀

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 get sent back to the sender through the same leg. 🦋
• this gets called from the managing Net::SIP::Dispatcher object whenever a new packet arrives. 📬
• it returns TRUE if the packet was fully handled by this object — which is the case if the packet was not authorized, so a 401 or 407 (if "i_am_proxy") response got sent back. 😤
• it returns FALSE if the packet was authorized and should be handled by the next object in the Net::SIP::ReceiveChain. and in that case, it usually changes the packet to remove the local authorization information. sneaky little cleanup moment. ✨

ngl bestie, the whole deal here is simple: authorized packets move along the chain, unauthorized ones get a 401/407 thrown at them. don't fight it. 💀

---

and that's the whole page, fr fr — brought to you by perl v5.40.1, dated 2025-12-07, from the User Contributed Perl Documentation collection. slay, go authorize some packets, ily 🫶💖✨