diff -r 733187d496d0 -r 8ec65b8f6e2c opensips/uac-reauth.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/opensips/uac-reauth.txt	Wed Feb 10 21:25:01 2010 +0100
@@ -0,0 +1,82 @@
+UAC module authentication extention (contribution)
+
+Problem
+
+A problem involving SIP authentication has plagued OpenSIPS for years.
+Because OpenSIPS is a proxy it may not manipulate the CSEQ of incoming
+requests or responses. When a UAC sends a SIP message which triggers
+an authentication challenge from another proxy or external UAS, OpenSIPS
+may receive a SIP response message with a 401 or 407 code.
+
+The UAC module provides a function uac_auth() to allow OpenSIPS to
+authenticate, however it is of limited utility because any SIP compliant
+proxy, PBX, or UAS sending such authentication challenges expects the
+CSEQ of the succeeding request to be different than the preceding one.
+
+Solution
+
+While somewhat of a hack, one solution to this problem is to forward
+code 401 and 407 responses to the UAC which will formulate an
+authorization header, insert it into the original request, and
+send the message again after incrementing the CSEQ. OpenSIPS
+receives the new request and passes it with success this time.
+
+This solution requires new hack logic to allow OpenSIPS to provide
+the uac_auth() function inside of request routing blocks, whereas
+the unmodified versions of OpenSIPS allow usage of uac_auth() only
+in failure routes.
+
+Usage
+
+To use the new logic simply follow the instructions of uac_auth() usage
+on incoming SIP requests (for example INVITE) inside a main or secondary
+routing block like so:
+
+  if (!load_gws()) {
+      send_reply("500", "Server Internal Error");
+      exit;
+  }
+  if (!next_gw()) {
+      send_reply("503", "Service Unavailable");
+      exit;
+  }
+  if ($avp(s:authuser) == "") {  # this is in case no user exists
+      $avp(s:authuser) = $fU;    # in the gw database table row
+  }
+  if ($hdr(P-hint) != "lcr applied") {
+      append_hf("P-hint: lcr applied\r\n");
+  }
+
+  # the following uac_auth avp parameters are filled in
+  # by the lcr itself, through a patch to its datatables
+  uac_auth();   # patched for use in request route as well
+  route(1);     # forward to gateway provider
+
+Location
+
+http://scm.europalab.com/contrib/opensips/
+http://scm.europalab.com/contrib/file/tip/opensips/
+http://scm.europalab.com/contrib/file/tip/opensips/uac-reauth.txt
+http://scm.europalab.com/contrib/file/tip/opensips/uac-reauth.diff
+
+Instructions
+
+To integrate this contributed logic into the source code tree of
+a OpenSIPS distribution, download the unified diff and use the
+patch(1) command:
+
+  $ cd /tmp && mkdir uac-patch && cd uac-patch
+  $ wget http://scm.europalab.com/contrib/raw-file/tip/opensips/uac-reauth.diff
+  $ tar zxf /tmp/opensips-<version>-tls.tar.gz
+  $ cd opensips-<version>-tls
+  $ patch -p0 <../uac-reauth.diff
+
+Disclaimer
+
+This software contribution is based on source code from OpenSIPS SVN
+revision 6590. The author makes no guarantees as to this contribution.
+A user who downloads and executes it does so at his own risk.
+
+Michael Schloh von Bennewitz
+http://michael.schloh.com/
+Wednsday, 10. February 2010