Browse code

examples with pbx/voicemail added; more on authetnication policy

Jiri Kuthan authored on 19/01/2003 20:03:55
Showing 2 changed files
... ...
@@ -18,6 +18,7 @@
18 18
 <!ENTITY execstep4 SYSTEM "../../examples/exec_s4.cfg">
19 19
 <!ENTITY execstep5 SYSTEM "../../examples/exec_s5.cfg">
20 20
 <!ENTITY execstep5b SYSTEM "../../examples/exec_s5b.cfg">
21
+<!ENTITY ccdiversion SYSTEM "../../examples/ccdiversion.cfg">
21 22
 <!ENTITY releasenotes SYSTEM "../../NEWS">
22 23
 <!ENTITY install SYSTEM "../../INSTALL">
23 24
 
... ...
@@ -2482,7 +2483,7 @@ modparam("usrloc", "db_url","sql://ser:secret@dbhost/ser")
2482 2482
 			    </programlisting>
2483 2483
 			</para>
2484 2484
 	    </section> <!-- user aliases -->
2485
-	    <section>
2485
+	    <section id=acl>
2486 2486
 		<title>Access Control (PSTN Gateway)</title>
2487 2487
 			<para>
2488 2488
 			    It is sometimes important to exercise some sort of
... ...
@@ -2914,7 +2915,8 @@ if (!lookup("location")) {
2914 2914
 		</para>
2915 2915
 	    </section> <!-- NAT traversal -->
2916 2916
 	    <section>
2917
-		<title>Prevention of Unauthorized Domain Name Use in From</title>
2917
+		<title>Authentication Policy: Prevention of Unauthorized Domain 
2918
+		    Name Use in From and More</title>
2918 2919
 		<para>
2919 2920
 		    Malicous users can claim a name of domain, to which they do 
2920 2921
 		    not administratively belong, in From header field. This
... ...
@@ -2961,8 +2963,115 @@ if (search("^(f|From):.*foo.bar")) {
2961 2961
 };
2962 2962
 		    </programlisting>
2963 2963
 		</para>
2964
+		<para>
2965
+		    In general, the authentication policy may be very rich. You may not
2966
+		    forget each request deserves its own security and you need to 
2967
+		    decide whether it shall be authenticated or not. As mentioned
2968
+		    above, in closed networks, you may want to authenticate absolutely 
2969
+		    every request. That however prohibits traffic from users from
2970
+		    other domains. A pseudo-example of a reasonable policy is attached:
2971
+		    it looks whether a request is registration, it claims to originate
2972
+		    from our domain in From header field, or is a local request to
2973
+		    another domain.
2974
+		    <programlisting format="linespecific">
2975
+# (example provided by Michael Graff on [serusers] mailing list
2976
+if (to me):
2977
+    if register
2978
+          www_authorize or fail if not a valid register
2979
+          done
2980
+    if claiming to be "From" one of the domains I accept registrations for
2981
+          proxy_authorize
2982
+          done
2983
+    if not to me (I'm relaying for a local phone to an external address)
2984
+          proxy_authorize
2985
+          done
2986
+		    </programlisting>
2987
+		</para>
2988
+		<para>
2989
+		    You also may want to apply additional restriction to how
2990
+		    digest username relates to usernames claimed in From and
2991
+		    To header fields. For example, the <command moreinfo="none">check_to</command>
2992
+		    action enforces the digest id to be equal to username
2993
+		    in To header fields. That is good in preventing someone
2994
+		    with valid credentials to register as someone else
2995
+		    (e.g., sending a REGISTER with valid credentials of
2996
+		    "joe" and To belonging to "alice"). Similarly,
2997
+		    <command moreinfo="none">check_from</command> is used
2998
+		    to enforce username in  from to equal to digest id.
2999
+		    <note>
3000
+			<para>
3001
+			    There may be a need for a more complex relationship
3002
+			    between From/To username and digest id. For example,
3003
+			    providers with an established user/password database
3004
+			    may wish to keep using it, whereas permitting users
3005
+			    to claim some telephone numbers in From. To address
3006
+			    such needs generally, there needs to be a 1:N mapping
3007
+			    between digest id and all usernames that are acceptable
3008
+			    for it. This is being addressed in a newly contributed
3009
+			    module "domain", which also addresses more generally
3010
+			    issues of domain matching for multidomain scenarios.
3011
+			</para>
3012
+		    </note>
3013
+		</para>
3014
+		<para>
3015
+		    Other operational aspect affecting the authentication policy
3016
+		    is guarding PSTN gateways (see <xref linkend="acl">). There
3017
+		    may be destinations that are given away for free whereas
3018
+		    other destinations may require access control using
3019
+		    group membership, to which  authentication is a prerequisity.
3020
+		</para>
2964 3021
 
2965
-	    </section> <!-- faked froms -->
3022
+	    </section> <!-- authentication policy, faked froms -->
3023
+	    <section>
3024
+		<title>Connecting to PBX Voicemail Using a Cisco Gateway</title>
3025
+		<para>
3026
+		    In some networks, administrators may wish to utilize their
3027
+		    PBX voicemail systems behind PSTN gateways. There is a practical problem
3028
+		    in many network settings: it is not clear for whom a call to
3029
+		    voicemail is. If voicemail is identified by a single number,
3030
+		    which is then put in INVITE's URI, there is no easy way to
3031
+		    learn for whom a message should be recorded. PBX voicemail
3032
+		    utilize that PSTN protocols signal the number of originally
3033
+		    called party. If you wish to make the PBX voicemail work,
3034
+		    you need to convey the number in SIP and translate it in
3035
+		    PSTN gateways to its PSTN counterpart.
3036
+		</para>
3037
+		<para>
3038
+		    There may be many different ways to achieve this scenario. Here
3039
+		    we describe the proprietary mechanism Cisco gateways use and how to 
3040
+		    configure <application moreinfo="none">ser</application> to
3041
+		    make the gateways happy. Cisco gateways expect the number
3042
+		    of originally called party to be located in proprietary
3043
+		    <varname>CC-Diversion</varname> header field. When a SIP 
3044
+		    INVITE sent via a PSTN gateway to PBX voicemail has number
3045
+		    of originally called party in the header field, the voicemail
3046
+		    system knows for whom the incoming message is. That is at least
3047
+		    true for AS5300/2600 with Cisco IOS 12.2.(2)XB connected to
3048
+		    Nortel pbxs via PRI. (On the other hand, 12.2.(7b) is known
3049
+		    not to work in this scenario.)
3050
+		</para>
3051
+		<para>
3052
+		    <application moreinfo="none">ser</application> needs then to
3053
+		    be configured to append the <varname>CC-Diversion</varname>
3054
+		    header field name for INVITEs sent to PBX voicemail.
3055
+		    The following script shows that: when initial forwarding
3056
+		    fails (nobody replies, busy is received, etc.), a new branch
3057
+		    is initiated to the pbx's phone number. 
3058
+		    <command moreinfo="none">append_urihf</command> is used to
3059
+		    append the <varname>CC-Diversion</varname> header field. It
3060
+		    takes two parameters: prefix, which includes header name,
3061
+		    and suffix which takes header field separator. 
3062
+		    <command moreinfo="none">append_urihf</command> inserts
3063
+		    original URI between those two.
3064
+		    <example>
3065
+			<title>Forwarding to PBX/Voicemail via Cisco Gateways</title>
3066
+			<programlisting format="linespecific">
3067
+&ccdiversion;
3068
+			</programlisting>
3069
+		    </example>
3070
+		    
3071
+		</para>
3072
+	    </section>
2966 3073
 	</section> <!-- howtos -->
2967 3074
 
2968 3075
 	<section>
... ...
@@ -3001,13 +3110,16 @@ if (search("^(f|From):.*foo.bar")) {
3001 3001
 		    </answer>		    
3002 3002
 		</qandaentry>
3003 3003
 		<qandaentry>
3004
+			
3004 3005
 		    <question>
3006
+			        
3005 3007
 			<para>
3006
-			    <anchor id="msmbug">
3008
+			
3007 3009
 			    Windows Messenger authentication fails.
3008 3010
 			</para>
3009 3011
 		    </question>
3010 3012
 		    <answer>
3013
+			<anchor id="msmbug">
3011 3014
 			<para>
3012 3015
 			    The most likely reason for this problem is a bug
3013 3016
 			    in Windows Messenger. WM only authenticates if
... ...
@@ -3487,8 +3599,8 @@ print
3487 3487
 		</example>
3488 3488
 
3489 3489
 		<example>
3490
-			<title>Showing User Contacts Using serctl</title>
3491
-			<para>
3490
+		    <title>Showing User Contacts Using serctl</title>
3491
+		    <para>
3492 3492
 			Another example of use of FIFO is accessing server's
3493 3493
 			in-memory user location database. That's a very powerful
3494 3494
 			feature: web applications and other tools can use it
... ...
@@ -3498,9 +3610,12 @@ print
3498 3498
 			FIFO command <command>ul_show_contact</command> to
3499 3499
 			retrieve current whereabouts of user "jiri".
3500 3500
 			<programlisting>
3501
+<![CDATA[
3501 3502
 [jiri@fox ser]$ serctl fifo ul_show_contact location jiri
3502 3503
 <sip:195.37.78.160:14519>;q=0.00;expires=1012
3504
+]]>
3503 3505
 			</programlisting>
3506
+		    </para>
3504 3507
 		</example>
3505 3508
 	    </para>
3506 3509
 	    <para>
3507 3510
new file mode 100644
... ...
@@ -0,0 +1,27 @@
0
+# $Id$
1
+
2
+# ------------------ module loading ----------------------------------
3
+
4
+loadmodule "modules/textops/textops.so"
5
+loadmodule "modules/sl/sl.so"
6
+loadmodule "modules/tm/tm.so"
7
+
8
+# ----------------- setting module-specific parameters ---------------
9
+
10
+route{
11
+	# if we do not get a positive reply, continue at reply_route[2]
12
+	t_on_negative("2");
13
+	# forward the request to all destinations in destination set now 
14
+	t_relay();
15
+}
16
+
17
+reply_route[2] {
18
+	# request failed (no reply, busy, whatever) ... forward it again
19
+	# to pbx's voicemail at phone number 6000 via Cisco gateway at
20
+	# 192.168.10.10; append proprietary CC-Diversion header field with
21
+	# original request uri in it, so that the gateway and voicemail
22
+	# know, whom the request was originally intended for
23
+	append_branch("sip:6000@192.168.10.10");
24
+	append_urihf("CC-Diversion: ", "\r\n");
25
+}
26
+