UAC Module

Bogdan-Andrei Iancu

   <bogdan@voice-system.ro>

Ramona-Elena Modroiu

   <team@voice-system.ro>

Edited by

Bogdan-Andrei Iancu

   <bogdan@voice-system.ro>

Edited by

Ramona-Elena Modroiu

   <team@voice-system.ro>

   Copyright © 2005-2009 Voice Sistem
   Revision History
   Revision $Revision: 6049 $ $Date: 2009-08-22 23:33:44 +0300
                              (Sat, 22 Aug 2009) $
     __________________________________________________________

   Table of Contents

   1. Admin Guide

        1.1. Overview
        1.2. Dependencies

              1.2.1. OpenSIPS Modules
              1.2.2. External Libraries or Applications

        1.3. Exported Parameters

              1.3.1. restore_mode (string)
              1.3.2. restore_passwd (string)
              1.3.3. rr_from_store_param (string)
              1.3.4. rr_to_store_param (string)
              1.3.5. credential (string)
              1.3.6. auth_realm_avp (string)
              1.3.7. auth_username_avp (string)
              1.3.8. auth_password_avp (string)

        1.4. Exported Functions

              1.4.1. uac_replace_from(display,uri)
                      uac_replace_to(display,uri)

              1.4.2. uac_replace_from(uri) uac_replace_to(uri)
              1.4.3. uac_restore_from() uac_restore_to()
              1.4.4. uac_auth()

   List of Examples

   1.1. Set restore_mode parameter
   1.2. Set restore_passwd parameter
   1.3. Set rr_from_store_param parameter
   1.4. Set rr_to_store_param parameter
   1.5. Set credential parameter
   1.6. Set auth_realm_avp parameter
   1.7. Set auth_username_avp parameter
   1.8. Set auth_password_avp parameter
   1.9. uac_replace_from/uac_replace_to usage
   1.10. uac_replace_from/uac_replace_to usage
   1.11. uac_restore_from/uac_restore_to usage
   1.12. uac_auth usage

Chapter 1. Admin Guide

1.1. Overview

   UAC (User Agent Client) module provides some basic UAC
   functionalities like FROM / TO header manipulation
   (anonymization) or client authentication.

   Known limitations in this version:
     * authentication does not support qop auth-int, just qop
       auth;
     * CSeq not increased during authentication - the response may
       be rejected.

1.2. Dependencies

1.2.1. OpenSIPS Modules

   The following modules must be loaded before this module:
     * TM - Transaction Module
     * RR - Record-Route Module, but only if restore mode for FROM
       URI is set to "auto".

1.2.2. External Libraries or Applications

   The following libraries or applications must be installed
   before running OpenSIPS with this module loaded:
     * None

1.3. Exported Parameters

1.3.1. restore_mode (string)

   There are 3 mode of restoring the original headers (FROM/TO)
   URI:
     * "none" - no information about original URI is stored;
       restoretion is not possible.
     * "manual" - all following replies will be restored, but not
       also the sequential requests - this must be manually
       updated based on original URI.
     * "auto" - all sequential requests and replies will be
       automatically updated based on stored original URI.

   This parameter is optional, it's default value being "auto".

   Example 1.1. Set restore_mode parameter
...
modparam("uac","restore_mode","auto")
...

1.3.2. restore_passwd (string)

   String password to be used to encrypt the RR storing paramter
   (when replacing the TO/FROM headers). If empty, no encryption
   will be used.

   Default value of this parameter is empty.

   Example 1.2. Set restore_passwd parameter
...
modparam("uac","restore_passwd","my_secret_passwd")
...

1.3.3. rr_from_store_param (string)

   Name of Record-Route header parameter that will be used to
   store (encoded) the original FROM URI.

   This parameter is optional, it's default value being "vsf".

   Example 1.3. Set rr_from_store_param parameter
...
modparam("uac","rr_from_store_param","my_Fparam")
...

1.3.4. rr_to_store_param (string)

   Name of Record-Route header parameter that will be used to
   store (encoded) the original TO URI.

   This parameter is optional, it's default value being "vst".

   Example 1.4. Set rr_to_store_param parameter
...
modparam("uac","rr_to_store_param","my_Tparam")
...

1.3.5. credential (string)

   Contains a multiple definition of credentials used to perform
   authentication.

   This parameter is required if UAC authentication is used.

   Example 1.5. Set credential parameter
...
modparam("uac","credential","username:domain:password")
...

1.3.6. auth_realm_avp (string)

   The definition of an AVP that might contain the realm to be
   used to perform authentication.

   If you define it, you also need to define "auth_username_avp"
   (Section 1.3.7, "auth_username_avp (string)") and
   "auth_username_avp" (Section 1.3.8, "auth_password_avp
   (string)").

   Example 1.6. Set auth_realm_avp parameter
...
modparam("uac","auth_realm_avp","$avp(i:10)")
...

1.3.7. auth_username_avp (string)

   The definition of an AVP that might contain the username to be
   used to perform authentication.

   If you define it, you also need to define "auth_realm_avp"
   (Section 1.3.6, "auth_realm_avp (string)") and
   "auth_username_avp" (Section 1.3.8, "auth_password_avp
   (string)").

   Example 1.7. Set auth_username_avp parameter
...
modparam("uac","auth_username_avp","$avp(i:11)")
...

1.3.8. auth_password_avp (string)

   The definition of an AVP that might contain the password to be
   used to perform authentication.

   If you define it, you also need to define "auth_password_avp"
   (Section 1.3.8, "auth_password_avp (string)") and
   "auth_username_avp" (Section 1.3.8, "auth_password_avp
   (string)").

   Example 1.8. Set auth_password_avp parameter
...
modparam("uac","auth_password_avp","$avp(i:12)")
...

1.4. Exported Functions

1.4.1.  uac_replace_from(display,uri) uac_replace_to(display,uri)

   Replace in FROM/TO header the display name and the URI part.

   display and URI parameters can include pseudo-variables.

   IMPORTANT: calling the function more than once per branch will
   lead to inconsistent changes over the request.Be sure you do
   the change only ONCE per branch. Note that calling the function
   from REQUEST ROUTE affects all the branches!, so no other
   change will be possible in the future. For per branch changes
   use BRANCH and FAILURE route.

   This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and
   FAILURE_ROUTE.

   Example 1.9. uac_replace_from/uac_replace_to usage
...
# replace both display and uri
uac_replace_from("$avp(s:display)","$avp(s:uri)");
# replace only display and do not touch uri
uac_replace_from("batman","");
# remove display and replace uri
uac_replace_from("","sip:robin@gotham.org");
# remove display and do not touch uri
uac_replace_from("","");
...

1.4.2.  uac_replace_from(uri) uac_replace_to(uri)

   Replace in FROM/TO header the URI part without altering the
   display name.

   URI parameter can include pseudo-variables.

   This function can be used from REQUEST_ROUTE.

   Example 1.10. uac_replace_from/uac_replace_to usage
...
uac_replace_from("sip:batman@gotham.org");
...

1.4.3.  uac_restore_from() uac_restore_to()

   This function will check if the FROM/TO URI was modified and
   will use the information stored in header parameter to restore
   the original FROM/TO URI value.

   NOTE - this function should be used only if you configured
   MANUAL restoring of the headers (see restore_mode param). For
   AUTO and NONE, there is no need to use this function.

   This function can be used from REQUEST_ROUTE.

   Example 1.11. uac_restore_from/uac_restore_to usage
...
uac_restore_from();
...

1.4.4.  uac_auth()

   This function can be called only from failure route and will
   build the authentication response header and insert it into the
   request without sending anything.

   This function can be used from FAILURE_ROUTE.

   Example 1.12. uac_auth usage
...
uac_auth();
...