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.