1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
|
=head1 NAME
Net::SIP::Authorize - enforce authorization of packets
=head1 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 ]
);
=head1 DESCRIPTION
This package is used inside a L<Net::SIP::ReceiveChain> to make sure,
that requests are authorized before they get handled by the next
receiver in the chain.
=head1 CONSTRUCTOR
=over 4
=item new ( %ARGS )
This creates a new registar object, %ARGS can have the following keys:
=over 8
=item dispatcher
L<Net::SIP::Dispatcher> object manging the registar. Mandatory.
=item realm
The realm for the authentication request. Defaults to 'p5-net-sip'.
=item opaque
Optional value for C<opaque> parameter for the authentication request.
If none is given no C<opaque> parameter will be used.
=item user2a1
Either hash reference with C<user,a1_hex> mapping or callback, which gives
C<a1_hex> if called with C<user,realm>.
For the meaning of C<a1_hex> see RFC 2617.
=item user2pass
Either hash reference with C<user,password> mapping or callback,
which gives C<password> if called with C<user>.
This parameter will only be used if C<user2a1> does not result in
a defined C<a1_hex> for C<user>.
=item i_am_proxy
Flag if the object behind works as a proxy (e.g. L<Net::SIP::StatelessProxy>)
and sends C<Proxy-Authenticate> or if it is an endpoint
(e.g. L<Net::SIP::Endpoint>, L<Net::SIP::Registrar>) which sends
C<WWW-Authenticate>.
=item 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 L<Net::SIP::Authorize>
subclass (e.g. C<ToIsFrom> means C<Net::SIP::Authorize::ToIsFrom>)
which has a C<verify> function or a C<[\&callback]>.
The verify function or callback will be called with
C<($packet,$leg,$addr,$auth_user,$auth_realm)> where C<$packet> is
the request, C<$leg> the L<Net::SIP::Leg> object where the packet
came in, C<$addr> the senders address, C<$auth_user> the
username from the authorized user and C<$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:
=over 4
=item FromIsRealm
Succeeds if the senders domain is the realm or a subdomain of the realm.
=item FromIsAuthUser
Succeeds if the username of the sender equals the username used for
authorization.
=item ToIsFrom
Succeeds if To header equals From header. This can be used to make sure, that a
user can only call REGISTER for itself.
=back
Example:
filter => {
REGISTER => [
# all of these must succeed
[ 'ToIsFrom','FromIsRealm','FromIsAuthUser' ],
# or this
[ \&callback ],
],
INVITE => 'FromIsRealm',
}
=back
=back
=head1 METHODS
=over 4
=item receive ( PACKET,LEG,FROM )
PACKET is the incoming packet,
LEG is the L<Net::SIP::Leg> where the packet arrived and FROM
is the C<< "ip:port" >> of the sender. Responses will be send
back to the sender through the same leg.
Called from the managing L<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 C<401>
or C<407> (if C<i_am_proxy>) response was send back.
Returns FALSE if packet was authorized and should be handled
be the next object in the L<Net::SIP::ReceiveChain>.
In this case it usually changes the packet to remove the local
authorization information.
=back
|
