more details added to multidomain (thanks Jan), nats, and sat (requested recently again)

doc/tmemo/README

@@ -1,5 +1,5 @@
 This directory contains short technical memos documenting 
-best practices and technical decisions made or proposed
+operational practices and technical decisions made or proposed
 for ser or accompanying applications. The memos serve as 
 requests for comments in the literal sense (not to be confused
 with IETF's RFCs).
@@ -17,7 +17,3 @@ in plain ASCII. Their filenames consists of
 For example: tmemo-johndoe-backtobackua.txt
 No version numbers are used in filename -- these are displayed 
 in text and assigned by CVS server. 
-
---
-TODO: reasonable topics which I would like to be addressed here
-include NAT traversal and multidomain management. -jiri

doc/tmemo/tmemo-jiri-multidomain.txt

@@ -3,18 +3,19 @@ $Id$
 Draft Requirements for Automated Multidomain Support in SER
 ============================================================
 
-
-Jiri Kuthan, iptel.org, January 2003
+Jiri Kuthan, Jan Janak
+iptel.org
+January 2003
 
 
 Summary and Status
 ------------------
 
-Currently, maintenance of multiple domains is a very manual process
-in SER -- one needs to introduce new SQL tables, change scripts and
-restart SER on introduction of a new domain. This memo summarizes
-requirements for automation of this process. The holy goal is to
-make domain provisioning as easy as manipulating list of supported 
+Currently (ser version 0.8.10), maintenance of multiple domains is 
+a very manual process in SER -- one needs to introduce new SQL tables, 
+change scripts and restart SER on introduction of a new domain. This 
+memo summarizes requirements for automation of this process. The goal 
+is to make domain provisioning as easy as manipulating list of supported 
 domains via FIFO server in run-time. This memo currently ignores
 current implementation status -- parts of it have been implemented
 in existing (auth, usrloc, registrar) or new (domain) modules.
@@ -23,98 +24,155 @@ Most of issues raised here come from private or [serhelp] discussions
 with Jan and Juha -- forgive me if I missed something when I was
 compiling it.
 
-Call for Comments
------------------
-please, let me know if I missed something. If you are aware how the
-individual requirements have been implemented, just put it in there.
-
 
 Requirements
 ------------
 
-a) when a request comes, it needs to be understood, whether it belongs
+a) Identification of Served Domains
+
+   when a request comes, it needs to be understood, whether it belongs
    to one of maintained domain, or shall be forwarded somewhere else;
-   that's what SERVED_DOMAIN(URI) is good for; however, Before checking the
-   domain ownership, one needs to translate domain name to a canonical
-   form -- there may be many of names (domain name, host name, IP address,
-   and other DNS aliases), out of which only the canonical one is used for 
-   domain processing; that's what CANONIZE_DOMAIN is good for
 
-      it's good to be able to access (reload, or manipulate) the list of
-      served domains in server's runtime -- use FIFO for that
+
+      SQL_TABLE:     domain(domain)
+      SER module:    domain
+      COMMANDS:      is_from_local()
+                     is_uri_host_local()
+
+      FIFO commands: domain_reload
+                     domain_dump
+
+
+      comments: jh: "I use now 'is_uri_host_local'"
+
+
+
+b) Domain Name Canonization
+ 
+   situtations can occur when a domain is reachable under multiple
+   names; if that is the case, name canonization needs to be carried
+   out before the domain check in (a); this for example happens if 
+   phones are connected, which use IP addresses in URIs.
 
        SQL_TABLE: domains(name,canonical_name)
-                  served_domains(name)
+       COMMANDS: canonize_domain
+
+      Note that such scenarios increase implementation and deployment
+      complexity. We thus better recommend using phones which do use
+      domain names.
+
+	Domain Name Canonization hasn't been implemented yet.
+
+
+c) Multi-Domain User Lookup
+
+   user location module identifies users by username and canonical domain
+   name; 
+
+       SQL_TABLE: location(user,domain,contact)
+       COMMANDS: lookup(table_name)
 
-       COMMANDS: SERVED_DOMAIN(URI), CANONIZE_DOMAIN
+     To enable multi domain support in registrar, use the following
+     parameters: modparam("usrloc", "use_domain", 1) and
+                 modparam("registrar", "use_domain", 1)
 
-       IMPLEMENTATION STATUS: ???
 
+d) Domain Verification in From HF 
 
-b) secondly, one needs to be able to learn, whether request sender claims
+   one needs to be able to learn, whether request sender claims
    a relationship to served domains in his From header field. to prevent
    unauthorized use of a served domain name in From, which -- if relayed
    by SER and rubber-stamped with its transport address -- could look
    trustworthy, one needs to authenticate the request sender
 
-   That's what SERVED_DOMAIN(FROM) is good for.
 
-       COMMANDS: SERVED_DOMAIN(FROM)
+        COMMANDS: is_from_local()
+        SER module: domain
 
-       IMPLEMENTATION STATUS: ???
+       Note: If (b) can occur, canonization should take place first
 
-c) user location module identifies users by username and canonical domain
-   name; a failure to canonize domain name prior to usrloc lookup results
-   in an unseccessful lookup, if domain name in request is not canonical
 
-       SQL_TABLE: location(user,domain)
+e) Username Verification
 
-       IMPLEMENTATION STATUS: ???
-
-
-d) users may display one or more names legally in From header fields;
+   users may display one or more names legally in From header fields;
    for example, a gateway operator is committed by law to forward only
-   user names (phone numbers) to PSTN which are owned by that user;
+   user names (phone numbers) to PSTN which are "owned" by that user;
    it is thus important to be able to check whether a pair {digest_id,
    From user name} is valid; there may be many of these pairs (i.e., 
    there may be N valid Froms for 1 digest id); digest id may or may
    not be the same string as From; (the second case for example
    occurs when an ISP already has a user database, he wants to reuse
    for authentication, but wishes users to show their "phone numbers"
-   in From); That's what CHECK_FROM is good for.
+   in From); 
+
+   Similar practise should apply to validation of To header field for
+   registrations. Otherwise, nothing would prevent users with valid
+   credentials to claim someone else's address in To and grab all his
+   incoming requests.
+
+          SQL TABLE: uri(user, domain, uri_user)
+          SER module: auth
+          COMMANDS: check_from
+                    check_to
 
-         SQL TABLE: valid_user{digest_id, realm, user_from}
-         (or multiple user_from values may be alternatively part
-          of subscriber table too)
 
-         IMPLEMENTATION STATUS: ???
+     if you use modparam("auth", "use_uri_table", 1) then uri table will
+     be used to map From or To username to a generic one and the generic
+     username will be compared to digest credentials username. If you do
+     not use the parameter, From or To username and digest credentials
+     username must be same.
 
-e) users need to be challenged with a proper realm; to automate this process,
+f) Generating Realm in Digest Challenges
+
+   users need to be challenged with a proper realm; to automate this process,
    one can generate realm out of domain names in requests;  xxx_challenge should 
    then use domainname in From HF as realm; the only exception is www_challenge, 
-   in which case To HF is to be used for REGISTERs (not proxy_challenge, though)
+   in which case To HF is to be used for REGISTERs (not proxy_challenge, though);
+----?? does he do that??--------
+
+
+    ACTION: {proxy|www}_challenge(AUTO);
+
+      The function accepts realm as the first parameter, if you use an
+      empty string "" then the realm will be extracted from From or To
+      header field (depending on function used and message type).
 
-    If having (realm==domain name) is for some reasons too limiting, the 
-    served_domains table should include realm name associated with a given domain.
+      Note: If having (realm==domain name) is for some reasons too limiting, the 
+      served_domains table should include realm name associated with a given domain.
+      Hopefully, there is no case for such automated realm generation.
+      Not implemented, realm must be equal to domain name if f) is used.
 
-    If some phones can still only handle only IP and put them in
-    From/To, one could still use the domains table for canonization
-    prior to sending out the realm. (credentials based on a non-canonical
-    domain name will not match the subscribers table otherwise)
+      Note: if (b) can occur, canonization should take place first.
 
-         IMPLEMENTATION STATUS: ???
 
-f) users need be authenticated properly; that takes in multi-domain
+g) Verifying Digest Credentials
+   
+   users need be authenticated properly; that takes in multi-domain
    environment looking up their entry in subscriber database correctly;
    the entry is identified by digest username (without domain name if
    present) and realm; if credentials are hashed, one needs to maintain
    and verify two hashes: one for users putting domain name in digest
    id and one for users not doing so
 
-        IMPLEMENTATION STATUS: ???
+    ACTION: {proxy|www}_authenticate(AUTO);
+
+      Comment: jh: the authenticate functions check that to/from matches
+                   digest realm (which integrates (d))
+
+--------???----------
+     If there is a domain name in username in digest credentials, it
+     will be extracted and used as domain. realm parameter if digest
+     credentials cannot be used to pass domain because it is not
+     protected by the digest (username is protected). realm parameter in
+     digest credentials is used only to identifiy which credentials in
+     the message belong to the server.
+--------???----------
+
 
-g) aliases are same as  usrloc -- now, they are looked by
-   name and domain name
+g) User Aliases 
+
+   aliases are same as  usrloc -- now, they are looked by name and domain name,
+   that's it.
 
 To-Do
 -----
@@ -132,31 +190,42 @@ manipulate domains, served_domains and valid_user.
 Script Example:
 ----------------
 
-/* does it belong to any of my served domains ? */
-canonize_domains();  /* 195.37.77.101 ->iptel.org */
-if (my_domain("uri")) {
-     if (method=="REGISTER") {
-           if (!www_authenticate()) {
-                www_challenge("" /* realm from request HFs */...
-                break;
-           };
-           save_contacts();
-           break;
-      };
-      if (!lookup()) {
-           sl_send_reply("404", "NotFound");
-           break;
-      }
-};
-
-/* does someoneclaimto belong to one of our served domain? prove it! */
-if (my_domain("from")) { 
-   if (!proxy_authenticate()) {
-      proxy_challenge("" /* realm from request HFs */...
-      break;
-   };
-   if (!valid_from() ..../* can user "jiri" have 7271 in from? */
-      sl_send_reply("500", "Forbidden");
-      break;
-   };
-   
+  modparam("usrloc", "use_domain", 1)
+  modparam("registrar", "use_domain", 1)
+  modparam("auth", "use_uri_table", 1)
+  modparam("auth", "use_domain", 1)
+
+
+ 
+ /* does it belong to any of my served domains ? */
+ canonize_domains();  /* 195.37.77.101 ->iptel.org */
+ if (is_uri_host_local()) {
+      if (method=="REGISTER") {
+            if (!www_authenticate("")) {
+                 www_challenge("" /* realm from request HFs */...
+                 break;
+            };
+            if (!check_to()) ..../* can digest-id "u123" register as "jiri"? */
+                 sl_send_reply("500", "Forbidden");
+                 break;
+            };
+            save("location");
+            break;
+       };
+       if (!lookup("location")) {
+            sl_send_reply("404", "NotFound");
+            break;
+       }
+ };
+ 
+ /* does someoneclaimto belong to one of our served domain? prove it! */
+ if (is_from_local()) { 
+    if (!proxy_authenticate("")) {
+       proxy_challenge("" /* realm from request HFs */...
+       break;
+    };
+    if (!check_from() ..../* can user "jiri" have 7271 in from? */
+       sl_send_reply("500", "Forbidden");
+       break;
+    };
+

doc/tmemo/tmemo-jiri-nats.txt

@@ -0,0 +1,243 @@
+$Id$
+
+Deployment Experience with NAT Traversal
+========================================
+
+
+Jiri Kuthan, iptel.org, February 2002
+
+TOC
+----
+1. Summary
+2. Background
+3. Summary of NAT Traversal Methods
+   - using symmetric communication
+   - UPnP
+   - geek tweaks
+   - ALG
+   - STUN
+   - media relay 
+   - FCP
+4. Hints for SER Usage
+5. More references
+
+
+1. Summary
+----------
+
+We summarize currently deployed techniques for NAT traversal. This
+memo focuses on practical experience of users of SIP or/and SER have
+had with getting over NATs. It attempts to capture aspects like
+known configuration pitfalls, available devices, and known
+operational limitations. It also includes subjective, unverified
+user experience encountered on our mailing list to give readers
+rough feeling for how people tackle with NATs.
+
+2. Background
+-------------
+NAT is one of the most annoying issues that have ever happened to SIP.
+SIP communication is very dynamic -- it allows many parties to 
+participate in many sessions of various types and flavors. To address
+this dynamicity, transport addresses are dynamically negotiated using SIP.
+IP addresses and transport port numbers are advertised in SIP
+headers and SDP payloads. Unfortunately, all these addresses
+are invalid once they cross a NAT and leave an addressing realm.
+That means that signaling "as is" simply does not work with NATs. Many 
+techniques have been developed to deel with this ugly, ugly, really ugly
+problem. None of them is perfect -- it is all patchwork fixing
+what NATs have broken. Some of them better fit in some scenarios
+then others do, but there is no "best" method.  It will be probably
+affordability of the methods, easy of configuration and market who 
+will decide popularity ranking for the available methods.
+
+The problem is really big. Noone really knows how big, that is one of
+NAT properties -- they hide users. Many residential users use NATs
+to save money for IP addresses. GPRS networks are told to be NATted
+by 90%. Brian Carpenter (January 2001): “My hand waving estimate is 
+that 40% (160M) of users are behind a firewall and/or NAT, 50% (200M) 
+on dial-up, and 10% (40M) have direct always-on access. But there is 
+no way I can justify these numbers.”
+
+For sake of completeness: a straight-forward solution would be to
+deploy IPv6 and have so many addresses, that there would be need for
+NATs. However, as this memo is focused on practicability, issues
+related to IPv6 are not mentioned here.
+
+See the following link for a detailed discussion of NAT traversal scenarios:
+http://www.iptel.org/ietf/firewall/nat/#draft-ietf-sipping-nat-scenarios
+
+
+
+3. Summary of NAT Traversal Methods
+-----------------------------------
+
+
+----------------------------------------------------------------
+technique:    using symmetric communication
+description:  the method is based on limiting peer-to-peer communication
+              to client-server communication; server always sends to where
+              client is sending from
+requirements: phone devices that support symmetric communication;
+              existing species: Cisco's ATA
+configuration 
+practice:     ATAs need to be configured to advertise public address 
+              in signaling (Contacts, SDP), or learn it from REGISTER 
+              replies; alternatively, one can rewrite signaling using ser's
+              nethelper module; one needs to rewrite SIP anyway
+              because ATAs don't advertise their symmetricity;
+              http://www.cisco.com/univercd/cc/td/doc/product/voice/ata/atarn/186rn214.htm#xtocid17;
+              see more on use with ser in section 4
+limitations:  non-symmetric devices, like Messenger don't work;
+              servers need to be reachable -- it does not work if both 
+              devices are behind NAT
+comments:     jku: ATA is a very simple device, it has no display, I am 
+                anxiously waiting for more vendors to support symmetric signaling
+              jt, maxim: the "received" workaround in version 2.15 does not work
+references:   http://www.iptel.org/ietf/firewall/nat/#draft-ietf-sip-symmetric-response
+
+----------------------------------------------------------------
+technique:    UPnP
+description:  the method is based on controlling NATs from end-devices
+requirements: NATs and phones with UPnP support; Messenger and 
+              snom are known to support UPnP; there is linux
+              support for it
+configuration 
+practice:     of course, upnp requires by definition no configuration ;-)
+              (I'm not serious -- anyone actually tried it?)
+comments:     jh: but how many nat boxes support upnp?  last time i looked at 
+                ms upnp page, the list was very short.
+
+----------------------------------------------------------------
+technique:    geek tweaks
+description:  set-up port forwading manually
+configuration  
+practice:     you need to configure NATs to split its public-side port
+              numbers accross your private-side phones, and configure
+              the phones (if they allows so) to use these port numbers;
+              also, phones need to be configured to use publicly
+              reachable address in their payloads
+requriements: configurable NATs (many residental NATs are configurable)
+              and configurable phones (ATAs do that, I heard pingtel did
+              it too)
+----------------------------------------------------------------
+technique:    ALG
+description:  NATs need to have built-in application awareness which fixes
+              signaling and replaces private realm addresses with public
+              ones
+requirements: SIP-capable NAT 
+hardware:     we are currently aware of residential Intertex, bigger-scale
+              Ingate, enterprise Cisco/PIX
+comments:     jh: i like this one.  cisco ios nat that is built in every 
+                cisco router now has sip alg.  you must have very recent ios 
+                version though.
+              jdr (in a private chat): it requires too much application
+                awareness from router vendors
+              jku: when I use intertex, my ssh connections freeze after   
+                some time on-line, not all Ethernet devices work with it;
+                sometimes turning it off and on is needed
+
+----------------------------------------------------------------
+technique:    STUN
+description:  STUN is a simple protocol, with which phones can query the public
+              addresses with which they appear outside, and use them in signaling
+requirements: STUN-enabled phone (like k-phone, snom)
+limitations:  doesn't work over symmetric NATs 
+software:     - Maxim's working stund, which works on BSD too:
+                http://people.freebsd.org/~sobomax/stund_0.8.2.tgz.
+              - kphone from wirlabs supports Stun
+comments:     jh: we have tried kphone's stun in all mojor dsl providers in finland 
+                that nat their customers and haven't had problems with any.  in some 
+                cases you have to run stund in your outbound proxy and not in some 
+                other ip address. 
+              nils: kphone/stun is nicely working, except it expects replies on 
+                other port number than it sends from (i.e., it behaves like
+                a server rather than like a client); then, replies go to the
+                port advertised in Via, for which no association in NAT exists,
+                because the original request created one with another port
+                number
+              jku: many residential NATs are claimed NOT to be symmetric
+                (just jabber I heard)
+References:   http://www.iptel.org/ietf/firewall/nat/#draft-ietf-midcom-stun
+
+----------------------------------------------------------------
+technique:    media relay
+description:  make all communication go through a server; if the communication
+              is symmetric, this method works even if both parties are behind
+              symmetric NATs
+limitations:  scalability issues with bandwidth load put on the relay; RTT doubles
+hardware:     JAsomi has some, it is in use in FWD; other devices exist from
+              Kagoor Networks, and Newport Networks
+----------------------------------------------------------------
+technique:    FCP
+description:  Firewall Control Protocol allows proxy server to align NATs to needs
+              of applications; the technique is similar to ALG, except the application
+              logic is moved away from router builders to application builders
+limitations:  there is no standard -- the IETF/MIDCOM WG has failed to deliver 
+              reasonable output in reasonable time; no FCP client exists right now
+software:     FCP server for linux nats exist; FCP client for ser is still work
+              in progress
+References:   http://www.iptel.org/fcp/
+----------------------------------------------------------------
+
+
+4. Hints for SER USage
+----------------------
+
+ad symmetric communication -- how nathelper works)
+
+- It takes symmetric devices. ATAs are such, but they do not advertise their
+  capability. One needs to grant specil handling for devices claiming to be
+  ATA in their requests.
+- It takes fixing Contacts before they are stored or forwarded. That's what nathelper 
+  does. It replaces phones' contacts with requests' transport origin. It also
+  adds "symmetric ad" to SDP payload ('active')
+- Replies need to be checked too to see if UAS supports symmetric signaling.
+- UAS needs to understand the 'active' option. IOS does so.
+
+fone F: A:B     NAT N: X:Y       proxy/registrar D                       
+
+                  ~                                                /--------\
+/------\          ~            /-----------------\                 |        |
+|phone | -------->~----------->|ser w/nathelper  |<--------------->|other   |\
+\------/          ~            |as outbound      |                 |domains ||\
+                  ~            |proxy + registrar|                 \--------/||
+                               \-----------------/                    \------/|
+                                                                        \-----/  
+
+nathelper script example: (subject to ongoing changes, as ser is being refurbished)
+
+
+
+route {
+        if (search("User-Agent: Cisco ATA.*")) {
+                add_rport();
+                fix_nated_contact();
+        };
+        rewriteFromRoute();
+
+
+        [REGISTRATION STUFF STRIPPED]
+
+
+        if (method=="INVITE") {
+                addRecordRoute();
+        };
+
+
+        t_on_positive("1")
+        # forward to current uri now
+        if (!t_relay()) {
+                sl_reply_error();
+        };
+}
+
+
+reply_route[1] {
+        if (search("Server: Cisco ATA.*") {
+                fix_nated_contact();
+        }
+}
+
+Acknowledgments: nathelper module is courtesy of MAxim Sobolev.
+
+

doc/tmemo/tmemo-jiri-sat.txt

@@ -0,0 +1,217 @@
+$Id$
+
+About Rewriting From in SIP Requests
+====================================
+
+
+Jiri Kuthan, iptel.org, February 2002
+
+
+Summary
+-------
+After giving an introduction about general packet (1) and particular SIP
+rewriting (2) and claiming it is harmful, we describe an IP2PSTN scenario
+which asks for username translation. It is about the ability to display
+phone number associated with a SIP caller in PSTN networks. We show three 
+methods (3) then:
+a) translation in gateways, which is little invasive and little 
+   deployable 
+b) NAI, which is architecturally still clean and takes fortunately 
+   little knowledge of user-provisioning in gateways, but relies on
+   an non-existent protocol extension
+c) brute request rewriting which is architecturally ugly but works now
+We also give some implementation hints for number three (4).
+
+
+
+1. Packet Rewriting Harmful
+---------------------------
+
+
+Generally, message rewriting by elements in middle of a communication
+path is a questionable practise threatening transparency. 
+
+
+The best historical example is that of NATs. These devices are widely 
+adopted by user community because they help to preserve IP address 
+space and save consumers' money charged for IP addresses. Unfortunately, 
+they mangle messages between end-devices in a way that makes life very
+difficult. Particularly, with SIP signaling IP addresses advertised
+in payload are invalid once a SIP message leavs a natted network.
+
+
+As the NAT example shows, rewriting packets by elements in the middle 
+is a ticket for problems and is likely to introduce operational confusion. 
+Readers wishing to learn more about Internet transparency, and threats to it
+are encouraged to read 
+
+
+http://www.iptel.org/ietf/arch/#rfc2775
+http://www.iptel.org/ietf/arch/#draft-iab-arch-changes
+http://www.iptel.org/ietf/firewall/midcom/#rfc3234
+
+
+
+2. Background on SIP Rewriting
+------------------------------
+In SIP, the most important element in the middle of the end2end path
+is a proxy server. With few exceptions, it operates in read-only mode.
+As requests and replies traverse SIP proxy servers, the servers update
+request-URI, put/remove themselves in routing-related parts of message 
+headers (route/via/record-route header field stacks) and decrement 
+Max-Forwards.  Other well-known exception is removal of consumed 
+credentials at authentication proxies.
+
+
+Rest of SIP messages remains untouched. Message body, header fields
+identifying transaction and dialog (From/CSeq/To/Call-ID), and other
+header fields including those unknown are not modified. That establishes
+transparent end2end communication, which is a prerequisity to many
+end-2-end based features, such as reliability or security.
+
+
+Consider the security implications as an example of "what happens
+if I rewrite". If end-2-end security is striven for and say signed
+digests are attached to a message to prove its integrity, rewritten
+messages will be recognized as such and denied.
+
+
+3. Rewrite or Not
+--------------
+There may be cases in which rewriting some header fields may have
+benefits. A particular case raised has been a scenario with users
+owning both "nice" e-mail-like SIP addresses as well as numerical
+aliases for interoperation with PSTN. While the users commonly use
+their e-mail like addresses (sip:[email protected]), when they call
+to PSTN, a gateway needs to advertise user's phone number to the
+PSTN world. User's From needs to be translated to his phone number
+before PSTN signaling is started.
+
+
+There are multiple solutions. The safest is to make the gateway
+implement this translation. This solution takes no rewriting in
+the SIP path, the translation occurs at the place where the rest
+of all other signaling translations occurs too. Whereas architecturally
+nice, it is not easy to deploy. PSTN gateways are typically hardware
+boxes with limited configuration possibilities. Also, the translation 
+database is typically stored in a specialized user-provisioning system,
+with interfaces which most likely are not supported by the gateway.
+
+
+It seems thus easier to place this translation capability in proxy
+servers. Proxy servers have been designed as open platforms for
+programming. Like web servers, they can have many programming
+interfaces, interact with databases and exercise request processing
+logic. The translation can also occur without mangling the original
+request -- the translation just needs to be _appended_ to the
+request. Some of the NAI proposals in IETF can be used, as long as 
+the NAI information is understood by terminating gateway:
+http://www.iptel.org/ietf/security/identity/
+
+
+The problem with NAI is it does not exist yet. To address cases
+like the one above right now, users are left with brute rewriting of
+From header field.
+
+
+4. How to Rewrite
+-----------------
+
+If you are not yet discouraged by all the evil aspects of packet 
+mangling and do not wish to wait until NAI is deployed, here you are. 
+When rewriting From header field, caution is advised: all requests and 
+replies in both directions need to be  translated consistently. Transaction 
+and dialog matching will fail otherwise and break signaling completely.
+
+To achieve that, a proxy server must stay in the path and understand
+direction of a transaction wrt to session. That is because unlike
+in requests from callers, in requests from callee the To header
+field needs to be rewritten. Both these features can be achieved 
+using record-routing. 
+
+
+When an initial INVITE arrives, the proxy server looks at From,
+and may decide to rewrite it using a database. If it does so
+(ser's action "replace" from module "textops" is a good example
+of how to achieve it), it puts a record-route (RR) in the forwarded
+request. The RR enforces subsequent communication to visit the
+proxy and can be used to include helpful hints in uri parameters.
+(In general, any parameters can be added as RR is "owned" by 
+a proxy and extension uri parameters are permitted for RR in 
+SIP spec.)
+
+
+The parameters that a proxy server appends to the RR-uri may 
+describe the translation so that it can be used for subsequent
+messages without having to consult the translation database
+again. Also, they may be used to identify transactions's
+direction. From tag may be good for this purpose. If the
+recorded value matches From tag in subsequent requests, it is
+request from caller and From needs to be rewritten. If it matches
+to-tag, it is request from callee and To needs to be rewritten.
+
+
+
+UAC                     proxy       gateway (UAS)
+---                     -----       -------------
+
+
+T1
+
+
+INVITE                              INVITE
+From: joe;tag=123 ---->   X   ----> From: 729-927-1234;tag=123
+                                    RR: ;ifrom=joe;ojoe=729-927-1234;ftag=123
+
+180               <----   X   <---- 180
+From: joe;tag=123                   From: 729-927-1234;tag=123                                    
+
+
+200               <----   X   <---- 200
+From: joe;tag=123                   From: 729-927-1234;tag=123
+                                    RR: ;ifrom=joe;ofrom=729-927-1234;ftag=123
+
+
+T2
+
+
+BYE                                 BYE   
+From: joe;tag=123 ---->   X   ----> From: 729-927-1234;tag=123 
+R: ;ifrom=joe;ojoe=729...                                                   
+
+
+200               <----   X   <---- 200
+From: joe;tag=123                   From: 729-927-1234;tag=123
+
+
+T3
+
+
+BYE                                 BYE   
+To: joe;tag=123   <----   X   <---- To: 729-927-1234;tag=123 
+                                    R: ;ifrom=joe;ojoe=729-927-1234;ftag=123
+
+
+200               ---->   X   ----> 200
+To: joe;tag=123                     To: 729-927-1234;tag=123
+
+
+  RR denotes record-route, R route, only parameters are shown in
+  RR and R
+
+
+Note that one has to address rewriting of replies too; one needs to
+know which replies should be rewritten and how. There are two ways.
+One is through use of stateful transaction processing. A "rewriting"
+flag is stored along with rewritten transactions. It tells, whether
+From or To has been rewritten in relayed requests. If so, value from
+the original request is put back in relayed replies.
+(Transactional processing is best utilized in ser using TM callbacks.)
+
+The other design choice is stateless: putting all the translation
+information in Via, similarly to like it is put in RR.
+
+Also, one needs to establish aliases that make the rewritten address
+routable. Otherwise, attempts to use the translated address in From
+header field for subsequent communication would fail. That is (unlike
+with NATs, fortunately) a workable option.