(hopefully) all issues related to maintenance of multiple domains

discussed so far have been gathered here

doc/tmemo/tmemo-jiri-multidomain.txt

@@ -0,0 +1,162 @@
+$Id$
+
+Draft Requirements for Automated Multidomain Support in SER
+============================================================
+
+
+Jiri Kuthan, 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 
+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.
+
+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
+   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: domains(name,canonical_name)
+                  served_domains(name)
+
+       COMMANDS: SERVED_DOMAIN(URI), CANONIZE_DOMAIN
+
+       IMPLEMENTATION STATUS: ???
+
+
+b) secondly, 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)
+
+       IMPLEMENTATION STATUS: ???
+
+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)
+
+       IMPLEMENTATION STATUS: ???
+
+
+d) 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;
+   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.
+
+         SQL TABLE: valid_user{digest_id, realm, user_from}
+         (or multiple user_from values may be alternatively part
+          of subscriber table too)
+
+         IMPLEMENTATION STATUS: ???
+
+e) 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)
+
+    If having (realm==domain name) is for some reasons too limiting, the 
+    served_domains table should include realm name associated with a given domain.
+
+    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)
+
+         IMPLEMENTATION STATUS: ???
+
+f) 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: ???
+
+g) aliases are same as  usrloc -- now, they are looked by
+   name and domain name
+
+To-Do
+-----
+
+All tables should be ideally hashed and cached for rapid processing. All but
+usrloc (domains,served_domains,valid_user, and also subscribers, grp) are 
+read all the time and rarely updated. That's a reason why use of 
+a read-write lock would be beneficial. Writes only occur via FIFO 
+process when administrative changes occur.
+
+serctl and serweb should be enhanced to provide the ability to
+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;
+   };
+