Browse code

added: 1) NAT traversal howto 2) From checking howto 3)FIFO/ul_add example

Jiri Kuthan authored on 06/01/2003 01:17:13
Showing 1 changed files
... ...
@@ -1290,7 +1290,7 @@ if (method=="REGISTER") {
1290 1290
 		several times. The question is what is the final URI to which
1291 1291
 		the script fill forward any incoming request.
1292 1292
 		<example>
1293
-		    <title>URI-rewriting Quiz</title>
1293
+		    <title>URI-rewriting Exercise</title>
1294 1294
 		    <programlisting format="linespecific">
1295 1295
 exec_uri("echo sip:2234@foo.bar; echo > /dev/null");
1296 1296
 strip(2);
... ...
@@ -2798,6 +2798,126 @@ if (!lookup("location")) {
2798 2798
 			    
2799 2799
 			</para>
2800 2800
 	    </section> <!-- missed calls -->
2801
+	    <section>
2802
+		<title>NAT Traversal</title>
2803
+		<para>
2804
+		    NATs are worst things that ever happened to SIP. These devices
2805
+		    are very popular because they help to conserve IP address space
2806
+		    and save money charged for IP addresses. Unfortunately, they
2807
+		    translate addresses in a way which is not compatible with SIP.
2808
+		    SIP advertises receiver addresses in its payload. The advertised
2809
+		    addresses are invalid out of NATted networks. As a result,
2810
+		    SIP communication does not work accross NATs without extra
2811
+		    effort.
2812
+		</para>
2813
+		<para>
2814
+		    There are few methods that may be deployed to traverse NATs.
2815
+		    How proper their use is depends on the deployment scenario.
2816
+		    Unfortunatelly, all the methods have some limitations and
2817
+		    there is no straight-forward solution addressing all
2818
+		    scenarios. Note that none of these methods takes explicit
2819
+		    support in <application moreinfo="none">ser</application>.
2820
+		</para>
2821
+		<para>
2822
+		    The first issue is whether SIP users are in control of 
2823
+		    their NATs. If not (NATs are either operated by ISP or
2824
+		    they are sealed to prevent users setting them up), the
2825
+		    only method is use of a STUN-enabled phone. STUN is 
2826
+		    a very simple protocol used to fool NAT in such a way,
2827
+		    they permit SIP sessions. Currently, we are aware of
2828
+		    one softphone (kphone) and one hardphone (snom) with
2829
+		    STUN support, other vendors are working on STUN support
2830
+		    too. Unfortunately, STUN gives no NAT traversal
2831
+		    guarantee -- there are types of NATs, so called
2832
+		    symmetric NATs, over which STUN fails to work.
2833
+		    <note>
2834
+			<para>
2835
+			    There is actually yet another method to address
2836
+			    SIP-unaware, user-uncontrolled NATs. It is based
2837
+			    on a proxy server, which relays all signaling and
2838
+			    media and mangles packets to make them more
2839
+			    NAT-friendly. The very serious problem with this
2840
+			    method is it does not scale.
2841
+			</para>
2842
+		    </note>
2843
+		</para>
2844
+		<para>
2845
+		    If users are in control of their own NAT, as typically residential
2846
+		    users are, they can still use STUN. However, they may use other
2847
+		    alternatives too. One of them is to replace their NAT with
2848
+		    a SIP-aware NAT. Such NATs have built-in SIP awareness,
2849
+		    that patches problems caused by address translations. Prices
2850
+		    of such devices are getting low and there are available
2851
+		    implementations (Intertex, Cisco/PIX). No special support
2852
+		    in phones is needed.
2853
+		</para>
2854
+		<para>
2855
+		    Other emerging option is UPnP. UPnP is a protocol that allows
2856
+		    phones to negotiate with NAT boxes. You need UPnP support in
2857
+		    both, NAT and phones. As UPnP NATs are quite affordable,
2858
+		    costs are not an obstacle. Currently, we are aware of one
2859
+		    SIP phone (SNOM) with UPnP support.
2860
+		</para>
2861
+		<para>
2862
+		    Geeks not wishing to upgrade their firewall to a SIP-aware or
2863
+		    UPnP-enabled one may try to configure static address translation.
2864
+		    That takes phones with configuration ability to use fixed port
2865
+		    numbers and advertise outside address in signaling. Cisco phones
2866
+		    have this capability, for example. The NAT devices need to
2867
+		    be configured to translate outside port ranges to the 
2868
+		    ranges configured in phones.		    
2869
+		</para>
2870
+	    </section> <!-- NAT traversal -->
2871
+	    <section>
2872
+		<title>Prevention of Unauthorized Domain Name Use in From</title>
2873
+		<para>
2874
+		    Malicous users can claim a name of domain, to which they do 
2875
+		    not administratively belong, in From header field. This
2876
+		    behaviour cannot be generally prevented. The reason is
2877
+		    that requests with such a faked header field do not need
2878
+		    to visit servers of the domain in question. However, if they
2879
+		    do so, it is desirable to assure that users claiming
2880
+		    membership in a domain are actually associated with it.
2881
+		    Otherwise the faked requests would be relayed and appear
2882
+		    as coming from the domain, which would increase
2883
+		    credibility of the faked address and decrease credibility of
2884
+		    the proxy server.
2885
+		</para>
2886
+		<para>
2887
+		    Preventing unathorized domain name use in relayed requests 
2888
+		    is not difficult.
2889
+		    One needs to authenticate each request with name of the
2890
+		    served domain in From header field. To do so, one can
2891
+		    search for such a header field using <command moreinfo="none">search</command>
2892
+		    action (textops module) and force authentication if the
2893
+		    search succeeds.
2894
+		    <note>
2895
+			<para>
2896
+			    A straight-forward solution might be to authenticate
2897
+			    ALL requests. However, that only works in closed
2898
+			    networks in which all users have an account in the
2899
+			    server domain. In open networks, it is desirable to permit
2900
+			    incoming calls from callers from other domains without
2901
+			    any authentication. For example, a company may wish
2902
+			    to accept calls from unknown callers who are
2903
+			    new prospective customers.
2904
+			    
2905
+			</para>
2906
+		    </note>
2907
+		    <programlisting format="linespecific">
2908
+# does the user claim our domain "foo.bar" in From?
2909
+if (search("^(f|From):.*foo.bar")) {
2910
+        # if so, verify credential
2911
+	if (!proxy_authorize("foo.bar", "subscriber")) { 
2912
+              # don't proceed if credentials broken; challenge
2913
+	      proxy_challenge("foo.bar", "0");
2914
+	      break;
2915
+        };
2916
+};
2917
+		    </programlisting>
2918
+		</para>
2919
+
2920
+	    </section> <!-- faked froms -->
2801 2921
 	</section> <!-- howtos -->
2802 2922
 
2803 2923
 	<section>
... ...
@@ -3364,6 +3484,94 @@ EOF
3364 3484
 		    </programlisting>
3365 3485
 		</example>
3366 3486
 		</para>
3487
+	    <example>
3488
+		<title>Manipulation of User Contacts</title>
3489
+		<para>
3490
+		    The following example shows use of FIFO server to manipulate
3491
+		    user's contacts. This may be very practical, if for example
3492
+		    a user wishes to set up his cell phone number as his temporary
3493
+		    contact. The cell phone, which is behind a PSTN gateway, cannot
3494
+		    register automatically using SIP. The user needs to set 
3495
+		    forwarding manually through some convenient web interface.
3496
+		    The web interface needs to have the ability to upload new user's
3497
+		    contacts to <application moreinfo="none">ser</application>.
3498
+		    This is what the <command moreinfo="none">ul_add</command> FIFO
3499
+		    command is good far. Paremeterized by user's name, table name,
3500
+		    expiration time and wight, it allows external applications to
3501
+		    introduce new contacts to server's in-memory user location table.
3502
+		</para>
3503
+		<para>
3504
+		    The example is borrowed from <application moreinfo="none">serweb</application>,
3505
+		    <application moreinfo="none">ser</application>'s web 
3506
+		    PHP-written interface.
3507
+		    It consists of a short "stub" function which carries out
3508
+		    all mechanics of FIFO communication and of forming the FIFO
3509
+		    request.
3510
+		</para>
3511
+		<programlisting format="linespecific">
3512
+<![CDATA[
3513
+
3514
+/* construct and send a FIFO command; the command parameters $sip_address, 
3515
+   $expires are PHP variables originating from an HTML form
3516
+ */
3517
+	$fifo_cmd=":ul_add:".$config->reply_fifo_filename."\n".
3518
+		$config->ul_table."\n".			//table
3519
+		$user_id."\n".		//username
3520
+		$sip_address."\n".				//contact
3521
+		$expires."\n".					//expires
3522
+		$config->ul_priority."\n\n";		//priority
3523
+		$message=write2fifo($fifo_cmd, $errors, $status);
3524
+
3525
+/* .......... snip .................. */
3526
+
3527
+/* this is the stub function for communicating with FIFO server.
3528
+   it dumps a request to FIFO server, opens a reply FIFO and
3529
+   reads server's reply from it
3530
+*/
3531
+function write2fifo($fifo_cmd, &$errors, &$status){
3532
+	global $config;
3533
+
3534
+	/* open fifo now */
3535
+	$fifo_handle=fopen( $config->fifo_server, "w" );
3536
+	if (!$fifo_handle) {
3537
+		$errors[]="sorry -- cannot open fifo"; return;
3538
+	}
3539
+	
3540
+	/* create fifo for replies */
3541
+	@system("mkfifo -m 666 ".$config->reply_fifo_path );
3542
+
3543
+	/* add command separator */
3544
+	$fifo_cmd=$fifo_cmd."\n";
3545
+	
3546
+	/* write fifo command */
3547
+	if (fwrite( $fifo_handle, $fifo_cmd)==-1) {
3548
+	    @unlink($config->reply_fifo_path);
3549
+	    @fclose($fifo_handle);
3550
+		$errors[]="sorry -- fifo writing error"; return;
3551
+	}
3552
+	@fclose($fifo_handle);
3553
+	
3554
+	/* read output now */
3555
+	@$fp = fopen( $config->reply_fifo_path, "r");
3556
+	if (!$fp) {
3557
+	    @unlink($config->reply_fifo_path);
3558
+		$errors[]="sorry -- fifo reading error"; return;
3559
+	}
3560
+
3561
+	$status=fgetS($fp,256);
3562
+	if (!$status) {
3563
+	    @unlink($config->reply_fifo_path);
3564
+		$errors[]="sorry -- fifo reading error"; return;
3565
+	}
3566
+	
3567
+	$rd=fread($fp,8192);
3568
+	@unlink($config->reply_fifo_path);
3569
+	
3570
+	return $rd;
3571
+}
3572
+]]>		   
3573
+		</programlisting>
3574
+	    </example>
3367 3575
 	    <para>
3368 3576
 		See
3369 3577
 		<xref linkend="fiforeference"> for a complete listing
... ...
@@ -3763,7 +3971,7 @@ route[2] {
3763 3971
 			The set of actions applicable from within
3764 3972
 			<command moreinfo="none">reply_route</command> blocks is limited.
3765 3973
 			Permitted actions are URI-manipulation actions, logging and
3766
-			sending stateful replies using <command moreinfo="none">t_reply_unsafe</command>.
3974
+			sending stateful replies using <command moreinfo="none">t_reply</command>.
3767 3975
 			Use of other actions may lead to
3768 3976
 			unpredictable results. (We plan to add syntactical checks in the future
3769 3977
 			so that improper action use will be detected during server start-up.)
... ...
@@ -4172,7 +4380,8 @@ if (len_gt(1024)) {
4172 4380
 	    <title>Modules</title>
4173 4381
 	    <para>
4174 4382
 		Module description is currently located in READMEs of
4175
-		respective module directories.
4383
+		respective module directories. <filename moreinfo="none">README-MODULES</filename>
4384
+		lists all available modules, including their maturity status.
4176 4385
 		In the current <application moreinfo="none">ser</application>
4177 4386
 		distribution, there are the following modules:
4178 4387
 		<itemizedlist>